statekit 0.4.1

An immutable state-machine for validating predefined transitions.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
# 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.3 -> 0.4

Version 0.4 adds stateful traversal through `MachineInstance`. The release is additive and requires no changes to existing 0.3 code.

### New `MachineInstance` for stateful traversal of `Machine`

Version 0.4 introduces `MachineInstance` to allow for traversal of `Machine` states.

```rust
let machine = Machine::builder()
    .try_allow("draft", "approved")?
    .try_allow("approved", "draft")?
    .build()?;
    
let mut instance = machine.instance("draft")?;
assert_eq!(instance.state(), "draft");

instance.transition_to("approved")?;
assert_eq!(instance.state(), "approved");
assert!(instance.can_transition_to("draft"));

instance.transition_to("draft")?;
assert_eq!(instance.state(), "draft");
assert!(instance.can_transition_to("approved"));
```

Two `MachineInstance` values are equal when their machine definitions and current states are equal.

```rust
let machine1 = Machine::builder()
    .try_allow("draft", "approved")?
    .build()?;
    
let machine2 = Machine::builder()
    .try_allow("draft", "approved")?
    .build()?;

// Equal definitions constructed independently
let instance1 = machine1.instance("draft")?;
let instance2 = machine2.instance("draft")?;

assert_eq!(instance1, instance2);

// Instances created from the same Machine are also equal
// when their current states are equal.
let instance3 = machine1.instance("draft")?;
assert_eq!(instance1, instance3);
```
#### `StateError::UnknownInitialState` for `MachineInstance` errors 

The initial state of a `MachineInstance` must already exist in `Machine`. If initialized with a non-existent state then it will return `StateError::UnknownInitialState`.

```rust
let machine = Machine::builder()
    .try_allow("draft", "approved")?
    .build()?;
    
let result = machine.instance("unknown");

if let Err(StateError::UnknownInitialState { state }) = result {
    println!("Failed to initialize with {}!", state);
}
```
### `Machine::is_terminal` for stateless terminality queries

Version 0.4 introduces `Machine::is_terminal(state)` to determine whether a state has no outgoing transitions.

```rust
let machine = Machine::builder()
    .try_allow("draft", "approved")?
    .build()?;
    
assert!(!machine.is_terminal("draft"));
assert!(machine.is_terminal("approved"));
    
let mut instance = machine.instance("draft")?;
assert!(!instance.is_terminal());

instance.transition_to("approved")?;
assert!(instance.is_terminal());
```

### Migration summary 

Version 0.4 is additive and requires no changes to existing v0.3 code. 

- An instance over the machine definition can be created.
- Whether a state is terminal can be determined.

## 0.2 -> 0.3

Version 0.3 introduces first-class transition inspection and simplifies transition-target queries.

### Transitions can be enumerated directly

Version 0.3 introduces the public `Transition` type and `Machine::transitions`, allowing callers to inspect the directed transitions in a machine directly.

```rust
for transition in machine.transitions() {
    println!("{} -> {}", transition.source(), transition.target());
}
```

A `Transition` exposes its source and target state names through `source()` and `target()`.

Transitions are immutable and are exposed through `Machine::transitions()`.
Machine definitions continue to be constructed through `MachineBuilder`.

### `Machine::targets_from` now returns an iterator directly

Version 0.3 changes `Machine::targets_from` to return an iterator directly rather than `Option<impl Iterator>`.

When the source has no outgoing transitions, the returned iterator is empty. This includes unknown states and states that appear only as transition targets.

Version 0.2:
```rust
if let Some(targets) = machine.targets_from("source") {
    for target in targets { 
        println!("{target}");
    }
}
```

```rust
if machine.targets_from("completed").is_none() {
    // ...
}
```

Version 0.3:
```rust
let targets = machine.targets_from("source");

for target in targets { 
    println!("{target}");
}
```

```rust
let mut targets = machine.targets_from("no_source");

if targets.next().is_none() {
    println!("no outgoing transitions");
}
```

```rust
let targets: Vec<_> = machine.targets_from("no_source").collect();

if targets.is_empty() {
    println!("no outgoing transitions");
}
```

### `StateError::AmbiguousStateName` contains a `state` field
 
`StateError::AmbiguousStateName` now preserves the invalid state name in a `state` field, allowing callers to report the exact value that contained leading or trailing Unicode whitespace.

Version 0.2:
```rust
match result {
    Err(StateError::AmbiguousStateName) => { println!("{err}"); }
    _ => {}
}
```

Version 0.3:
```rust
match result {
    Err(StateError::AmbiguousStateName { state }) => { println!("{state}"); }
    _ => {}
}
```

### `MachineBuilder` no longer implements `Default` or `PartialEq`

Version 0.3 removes the `Default` and `PartialEq` implementations from `MachineBuilder`.

Machine builders should be created through `Machine::builder()` rather than `MachineBuilder::default()`.

Version 0.2:

```rust
let builder = MachineBuilder::default();
```

Version 0.3:

```rust
let builder = Machine::builder();
```

`PartialEq` was also removed because equality between builders is not part of Statekit's public domain contract. Code that directly compares `MachineBuilder` values must be updated to verify the resulting machine or other observable behavior instead.

Both trait removals are breaking changes.

### Migration summary

Most 0.2 consumers need to update code that handles `Machine::targets_from` or exhaustively matches `StateError::AmbiguousStateName`.

- `Machine::targets_from` now returns an iterator directly. No outgoing
  transitions are represented by an empty iterator.
- `StateError::AmbiguousStateName` now contains the invalid state name.
- `MachineBuilder::default()` is no longer available; use `Machine::builder()`.
- `MachineBuilder` no longer implements `PartialEq`.
- `Machine::transitions()` can be used to inspect transitions directly.

## 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`

In version 0.2, Machine definitions 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`.