State Machine Protocol

The State Machine (state_machine validation rule) lets you define the "Constitution" of a record's lifecycle: the legal status transitions a record may take. It is a flat, textbook finite-state-machine transition table that the write path enforces.

Why State Machines?

In the era of AI Agents, field-level validation is not enough. Large Language Models (LLMs) can "hallucinate" and attempt illogical data updates (e.g., moving a contract from draft directly to paid without going through approval).

The transition table provides a hard constraint layer:

• Deterministic: On update, if the state field changed and the new value is not listed under the current value, the write is rejected.
• Self-Documenting: The whole legal graph lives in one place, as data.
• Introspectable: UIs can grey out illegal buttons and an Agent can ask "from here, what's legal next?" instead of parsing a formula.

Definition

Add a state_machine rule to the object's validations array. The rule names the state field and declares a transitions map of { currentValue: [allowedNextValues] }.

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const PurchaseRequest = ObjectSchema.create({
  name: 'purchase_request',
  label: 'Purchase Request',

  fields: {
    status: Field.select({
      label: 'Status',
      required: true,
      options: [
        { label: 'Draft', value: 'draft', default: true },
        { label: 'Pending', value: 'pending' },
        { label: 'Approved', value: 'approved' },
        { label: 'Rejected', value: 'rejected' },
      ],
    }),
    amount: Field.number(),
  },

  validations: [
    {
      type: 'state_machine',
      name: 'purchase_status_flow',
      label: 'Purchase Status Flow',
      field: 'status',
      // Validated on update; insert sets the initial state from the
      // `default: true` select option (no separate `initial` key).
      events: ['update'],
      message: 'Invalid purchase status transition.',
      transitions: {
        draft: ['pending'],
        pending: ['approved', 'rejected'],
        // `approved` and `rejected` are dead-end states (no outgoing edges).
      },
    },
  ],
});

Structure

A state_machine rule shares the common validation-rule fields (name, label, message, severity, events, priority, active) with its siblings, plus two of its own:

Transitions

transitions is the whole legal graph. The keys are current state values; each value is the list of states the record may move to. A state with no key (or an empty array) is a dead-end with no outgoing edges.

transitions: {
  draft: ['pending'],
  pending: ['approved', 'rejected'],
}

Enforcement semantics

• On insert, the rule is a no-op — there is no prior state to transition from. The field-level select check already constrains the initial value, and the initial state is the option marked default: true.
• On update, if the state field changed and the new value is not in transitions[oldValue], the write is rejected.
• The check is lenient where it cannot reason: if the prior state is not described by the table (e.g. legacy or externally-written data), it does not block.
• Only a rule with severity: 'error' (the default) blocks the write; warning/info are logged.

Conditional transitions

A state_machine rule has no per-transition guard. To gate a transition on a predicate, add a sibling script or conditional validation rule (CEL) in the same validations array.

Introspection

Because the transition table is data, both UIs and Agents can ask "from this state, what's legal next?" instead of parsing a formula.

• In code, legalNextStates(objectSchema, field, currentState) from @objectstack/objectql returns the declared next states, [] for a known dead-end, or null when no state_machine rule governs the field.
• Over HTTP, GET /api/v1/meta/objects/:name/state/:field?from=:state returns { object, field, from, next }, where next is the legal-next list (or null).

Best Practices: File Structure

For complex business objects (like Lead, Opportunity, or Order), a transition table can grow large. To keep your object definition readable, extract the rule(s) into a plain TypeScript constant — there is no special *.state.ts format or StateMachineConfig type for object lifecycles; it is just an array of validation rules.

// src/objects/lead.validations.ts
export const leadValidations = [
  {
    type: 'state_machine' as const,
    name: 'lead_status_flow',
    field: 'status',
    message: 'Invalid lead status transition.',
    events: ['update'] as const,
    transitions: {
      new: ['qualified', 'unqualified'],
      qualified: ['converted', 'unqualified'],
    },
  },
];

// src/objects/lead.object.ts
import { ObjectSchema } from '@objectstack/spec/data';
import { leadValidations } from './lead.validations';

export const Lead = ObjectSchema.create({
  name: 'lead',
  // ... fields ...
  validations: leadValidations,
});

Multiple Lifecycles (Parallel State Lines)

In real enterprise systems, a single object often has multiple independent state lines. For example, an Order has:

• lifecycle — draft → submitted → confirmed → shipped → delivered
• payment — unpaid → partial → paid → refunded
• approval — pending → approved → rejected

These are N flat state_machine rules, one per state field, in the same validations array — not hierarchical or parallel statechart regions.

// src/objects/order.object.ts
import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Order = ObjectSchema.create({
  name: 'order',
  fields: {
    status: Field.select({ options: ['draft', 'submitted', 'confirmed', 'shipped', 'delivered'] }),
    payment_status: Field.select({ options: ['unpaid', 'partial', 'paid', 'refunded'] }),
    approval_status: Field.select({ options: ['pending', 'approved', 'rejected'] }),
  },
  validations: [
    {
      type: 'state_machine',
      name: 'order_lifecycle',
      field: 'status',
      message: 'Invalid order status transition.',
      transitions: {
        draft: ['submitted'],
        submitted: ['confirmed'],
        confirmed: ['shipped'],
        shipped: ['delivered'],
      },
    },
    {
      type: 'state_machine',
      name: 'order_payment',
      field: 'payment_status',
      message: 'Invalid payment status transition.',
      transitions: {
        unpaid: ['partial', 'paid'],
        partial: ['paid', 'refunded'],
        paid: ['refunded'],
      },
    },
    {
      type: 'state_machine',
      name: 'order_approval',
      field: 'approval_status',
      message: 'Invalid approval status transition.',
      transitions: {
        pending: ['approved', 'rejected'],
      },
    },
  ],
});