state-machine.mdx

title	State Machine
description	State Machine protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

XState-inspired State Machine Protocol

Used to define strict business logic constraints and lifecycle management.

Prevent AI "hallucinations" by enforcing valid valid transitions.

**Source:** `packages/spec/src/automation/state-machine.zod.ts`

TypeScript Usage

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, { type: Enum<'atomic' | 'compound' | 'parallel' | 'final' | 'history'>; entry?: string | { type: string; params?: Record<string, any> }[]; exit?: string | { type: string; params?: Record<string, any> }[]; on?: Record<string, string | { target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string } | { target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string }[]>; … }>	✅	State Nodes
on	Record<string, string | { target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string } | { target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string }[]>	optional

---

StateNode

Properties

Property	Type	Required	Description
type	Enum<'atomic' | 'compound' | 'parallel' | 'final' | 'history'>	✅
entry	string | { type: string; params?: Record<string, any> }[]	optional	Actions to run when entering this state
exit	string | { type: string; params?: Record<string, any> }[]	optional	Actions to run when leaving this state
on	Record<string, string | { target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string } | { target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string }[]>	optional	Map of Event Type -> Transition Definition
always	{ target?: string; cond?: string | { type: string; params?: Record<string, any> }; actions?: string | { type: string; params?: Record<string, any> }[]; description?: string }[]	optional
initial	string	optional	Initial child state (if compound)
states	Record<string, [StateNode](#statenode)>	optional
meta	{ label?: string; description?: string; color?: string; aiInstructions?: string }	optional

---

Transition

Properties

Property	Type	Required	Description
target	string	optional	Target State ID
cond	string | { type: string; params?: Record<string, any> }	optional	Condition (Guard) required to take this path
actions	string | { type: string; params?: Record<string, any> }[]	optional	Actions to execute during transition
description	string	optional	Human readable description of this rule

---