validation-first

What this skill does

# Validation-first development

Define state machines from requirements before implementation. Specifications say what the system MUST do. Encode compile-time properties in types first, then layer state machine modeling for properties types cannot express.

**Modern insight (2025)**: State machines exist on a spectrum from runtime enums to compile-time typestates. Use the strongest mechanism available. XState v5 introduces actor model semantics -- state machines are now first-class concurrent entities, not just enum switches.

See [approaches](references/approaches.md) for language-specific state machine mechanisms.
See [examples](references/examples.md) for brief state machine patterns per language.
See [formal-tools](references/formal-tools.md) for specification and model checking tools.

---

## State Machine Taxonomy (decision guidance)

| Level | Mechanism | Strength | Use When |
|-------|-----------|----------|----------|
| **Typestate** (compile-time) | Generic type params, phantom data | Invalid transitions unrepresentable | Protocol APIs, builder patterns, Rust FFI |
| **Statecharts** (hierarchical) | Nested states, parallel regions | Complex workflows, entry/exit | Game state, multi-modal UI, XState |
| **Flat FSM** (runtime) | Enum + match/switch | Simple, auditable | Order lifecycle, connection mgmt |
| **Actor model** | Independent entities, message passing | Concurrent state | Distributed systems, Erlang/Elixir, XState v5 |

**Default choice**: Use the strongest mechanism the language supports. Typestate in Rust, sealed classes in Kotlin, discriminated unions in TypeScript.

## Validation Levels

```
Type system (strongest) > State machine > Contract > Runtime check (weakest)
```

---

## When to Apply

- Protocol implementations (network, API, auth flows)
- Workflow engines (approval chains, CI/CD pipelines)
- Concurrent/distributed systems (coordination state)
- Order lifecycle (e-commerce, payments, shipping)
- Connection/session management
- Actor systems with message-driven state
- Event sourcing aggregates (command validation against current state)

## When NOT to Apply

- Stateless REST endpoints
- Pure data transformations (map/filter/reduce)
- Simple CRUD without lifecycle
- Configuration parsing
- Batch processing without state

---

## Anti-patterns

- **Boolean soup**: `{ isLoading: true, isError: true, data: X }` -- contradictory states representable. Use discriminated unions instead.
- **Stringly-typed states**: `state: "pending"` with no exhaustiveness check
- **Partial transition coverage**: Some transitions undefined -- runtime "impossible" states
- **Split-brain**: State and behavior in separate modules -- changes require cross-module updates
- **Invariants at boundaries only**: Check invariants at every transition, not just entry/exit
- **Implicit transitions**: State changes scattered across codebase -- impossible to audit
- **State explosion without hierarchy**: Flat FSM with 50+ states -- use statecharts (nested states)

---

## Pseudocode Template

```
STATE MACHINE: <Name>
  STATES: S1 | S2 | S3
  VARIABLES: var1: type, var2: type
  INIT: var1 = val, state = S1
  ACTION name(args): PRE: guard -> POST: new_state, effects
  INVARIANT: condition_that_always_holds
```

## Event Sourcing Integration

When state machines guard event-sourced aggregates:
1. Command arrives -> validate against current aggregate state machine
2. If transition valid -> emit immutable event
3. State rebuilt from event replay
4. Invalid transitions rejected before events created -- impossible to corrupt event log

---

## Workflow (language-neutral)

1. **PLAN** -- Identify states, variables, actions, invariants from requirements. Draw state diagram.
2. **CREATE** -- Define state machine spec using pseudocode template. Choose mechanism level (typestate/FSM/actor).
3. **VERIFY** -- Type-check, confirm exhaustive matching on all states, validate invariants hold at every transition.
4. **IMPLEMENT** -- Target code mirrors spec. One state type, one transition function, one invariant check per concern.

---

## Constitutional Rules (Non-Negotiable)

1. **CREATE First**: Define state machine specification from plan
2. **Invariants Must Hold**: All invariants verified at every transition
3. **Actions Must Type**: All actions type-check with exhaustive matching
4. **Implementation Follows Spec**: Target code mirrors specification structure

## Validation Gates

| Gate | Pass Criteria | Blocking |
|------|---------------|----------|
| Typecheck | No errors; exhaustive match where language enforces it | Yes |
| Invariants | All invariant assertions pass after each action | Yes |
| Tests | All state transition tests pass | If present |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Specification verified, ready for implementation |
| 11 | Checker not available |
| 12 | Syntax/type errors in specification |
| 13 | Invariant violation detected |
| 14 | Specification tests failed |
| 15 | Implementation incomplete |