statekit 0.4.1

An immutable state-machine for validating predefined transitions.
Documentation
---
project: statekit
category: specification
category-level: foundational
version: 0.4
status: active
review-status: reviewed
---
# Statekit Specification

## Purpose

This specification defines the Statekit domain model and the behavioral contracts between its components. It describes the semantics that implementations of Statekit must preserve while remaining subordinate to the durable intent and invariants defined by the Project Core.

## Machine

Machine is an immutable value-like definition of the allowed state transitions. 
### Construction
- Contains at least one logical transition.
- Contains only validated state names and transitions.
- Cycles between distinct states are permitted.
- Once constructed, its definition cannot change.
### Queries
- Determines whether an edge exists between two states.
- Exposes states, sources, transitions, and outgoing targets.
- Querying the transitions reachable from a state with no outgoing transitions produces an empty result. This includes states that appear only as transition targets and names that do not occur in the machine.
### Identity and Equality
- State names are matched exactly.
- Query input is not normalized or trimmed.
- Machine equality is based on the logical machine definition, independent of shared allocation identity.

## Machine Instance

Represents mutable traversal state over an immutable Machine definition.
### Construction
- The initial state of the instance must already exist in the machine definition.
### Current State
- The current state is always a state in the machine definition.
### Traversal
- The instance can transition from its current state only to a target allowed by the machine definition.
- A failed transition attempt has no observable effect on the instance.
### Terminality
- An instance is terminal when its current state has no outgoing transitions.
- A terminal instance cannot successfully transition.
### Independence
- Two instances referencing the same machine definition do not change each other's traversal state.
### Equality 
- Two instances are equal when their machine definitions are equal and their current states are equal.

## Machine Builder

Validates and builds the state-machine.
### Transition Addition
- Adds transitions between source and target states to the machine definition.
- Adding a duplicate transition does not change the machine definition.
### Validation Timing
- Validates requirements knowable about a proposed transition when the transition is added.
- Validates requirements knowable about the completed definition on build.
### Machine Construction
- A successful build produces a `Machine`.

## Transition

Represents a directed transition from a source state to a target state.
### Construction 
- A transition is defined by its source and target states.
- The source and target states must be different.
- Once constructed, its source and target cannot change.
### Equality 
- Two transitions with the same source and target represent the same logical transition.

## State Name

Represents the symbolic identity of a state.
### Construction
- A state name must not begin or end with Unicode whitespace.
- A state name must contain at least one non-whitespace character.
- State names may contain UTF-8 text.
- State names are not normalized or trimmed during construction.
### Identity
- Two states with the same state name represent the same logical state.
- State names are case-sensitive.

## Component Relationships

```
[Machine] -- Contains --> [Transition] -- Has Source --> [State Name]
                                       -- Has Target --> [State Name]
          -- Creates --> [Machine Instance]
```

```
MachineBuilder
      │
      │ builds
      ▼
   Machine
      │
      │ defines allowed
      ▼
 Transition
   │       │
 source   target
   │       │
   ▼       ▼
 State   State

Machine
   │
   │ creates / defines traversal for
   ▼
MachineInstance
```

## Compatibility

Public API changes follow semantic versioning.
Internal storage is not part of the Statekit domain contract.

Strengthening an invariant that causes previously valid input to be rejected is considered a behavioral compatibility change and must be intentional.

## Evidence

See [Project Core](./project-core.md).

Related testing documentation:

- [Unit Test Outline]./unit-test-outline.md
- [Property Test Outline]./property-test-outline.md