---
title: State Machine
description: State Machine protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

XState-inspired State Machine Protocol

Used to define strict business logic constraints and lifecycle management.

Prevent AI "hallucinations" by enforcing valid valid transitions.

<Callout type="info">
**Source:** `packages/spec/src/automation/state-machine.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ActionRef, Event, GuardRef, StateMachine, StateNode, Transition } from '@objectstack/spec/automation';
import type { ActionRef, Event, GuardRef, StateMachine, StateNode, Transition } from '@objectstack/spec/automation';

// Validate data
const result = ActionRef.parse(data);
```

---

## ActionRef

### Union Options

This schema accepts one of the following structures:

#### Option 1

Action Name

Type: `string`

---

#### Option 2

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ |  |
| **params** | `Record<string, any>` | optional |  |

---


---

## Event

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | Event Type (e.g. "APPROVE", "REJECT", "Submit") |
| **schema** | `Record<string, any>` | optional | Expected event payload structure |


---

## GuardRef

### Union Options

This schema accepts one of the following structures:

#### Option 1

Guard Name (e.g., "isManager", "amountGT1000")

Type: `string`

---

#### Option 2

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ |  |
| **params** | `Record<string, any>` | optional |  |

---


---

## StateMachine

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Unique Machine ID |
| **description** | `string` | optional |  |
| **contextSchema** | `Record<string, any>` | optional | Zod Schema for the machine context/memory |
| **initial** | `string` | ✅ | Initial State ID |
| **states** | `Record<string, [__schema0](./__schema0)>` | ✅ | State Nodes |
| **on** | `Record<string, string \| Object \| Object[]>` | optional |  |


---

## StateNode

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'atomic' \| 'compound' \| 'parallel' \| 'final' \| 'history'>` | ✅ |  |
| **entry** | `string \| Object[]` | optional | Actions to run when entering this state |
| **exit** | `string \| Object[]` | optional | Actions to run when leaving this state |
| **on** | `Record<string, string \| Object \| Object[]>` | optional | Map of Event Type -> Transition Definition |
| **always** | `Object[]` | optional |  |
| **initial** | `string` | optional | Initial child state (if compound) |
| **states** | `Record<string, [#](./#)>` | optional |  |
| **meta** | `Object` | optional |  |


---

## Transition

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **target** | `string` | optional | Target State ID |
| **cond** | `string \| Object` | optional | Condition (Guard) required to take this path |
| **actions** | `string \| Object[]` | optional | Actions to execute during transition |
| **description** | `string` | optional | Human readable description of this rule |


---

