State Transition Validator

Overview

You send a state machine, the state something is in, the event that just happened, and optionally the context your guards look at. We answer whether that event is allowed, which state it leads to, and which transition matched — or, when it is not allowed, exactly why: the state is unknown, the state is terminal, no transition covers this event, a guard was not satisfied, or two transitions matched and the outcome would be ambiguous. Guards are data, not code: six comparisons over values picked from your context by JSON Pointer, so a condition that looks like a formula is compared as the literal text it is. Nothing is stored, nothing is moved, and no transition action is run.

Status rules end up spread across controllers, migrations and background jobs, and they drift: one path allows a refund on a cancelled order, another does not. Declaring the machine as data and asking one skill keeps every service on the same answer, with the denial reason available to show a user.

When to use it

Scope

Non-goals

• Does not store or advance the machine — the answer is yours to act on
• Does not run transition actions, hooks or side effects
• Does not evaluate expressions, scripts or templates in conditions
• Does not invent transitions for events the machine does not declare
• Does not echo the context values your guards read

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"workflow.state_transition_validate","input":{"currentState":"pending","event":"pay","machine":{"states":[{"id":"pending"},{"id":"paid"}],"transitions":[{"id":"t-pay","from":"pending","event":"pay","to":"paid"}]}}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("workflow.state_transition_validate", {"machine":{"states":[{"id":"pending"},{"id":"paid"},{"id":"cancelled","terminal":true}],"transitions":[{"id":"t-pay","from":"pending","event":"pay","to":"paid","conditions":[{"value":"captured","op":"EQUALS","pointer":"/payment/status"}]},{"event":"cancel","to":"cancelled","from":"pending","id":"t-cancel"}]},"currentState":"pending","context":{"payment":{"status":"captured"}},"event":"pay"});

Errors

Other limits

Limitations

• Does not store or advance the machine — the answer is yours to act on
• Does not run transition actions, hooks or side effects
• Does not evaluate expressions, scripts or templates in conditions
• Does not invent transitions for events the machine does not declare
• Does not echo the context values your guards read
• Persisting the new state or emitting events, which stays your call
• Machines whose guards need arbitrary expressions or a rules engine
• Choosing between several allowed transitions — that is ambiguity here, not a priority question

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "workflow.state_transition_validate",
  "input": {
    "machine": {
      "states": [
        {
          "id": "pending"
        },
        {
          "id": "paid"
        },
        {
          "id": "cancelled",
          "terminal": true
        }
      ],
      "transitions": [
        {
          "id": "t-pay",
          "from": "pending",
          "event": "pay",
          "to": "paid",
          "conditions": [
            {
              "value": "captured",
              "op": "EQUALS",
              "pointer": "/payment/status"
            }
          ]
        },
        {
          "event": "cancel",
          "to": "cancelled",
          "from": "pending",
          "id": "t-cancel"
        }
      ]
    },
    "currentState": "pending",
    "context": {
      "payment": {
        "status": "captured"
      }
    },
    "event": "pay"
  }
}

Examples

{
  "machine": {
    "states": [
      {
        "id": "pending"
      },
      {
        "id": "paid"
      },
      {
        "id": "cancelled",
        "terminal": true
      }
    ],
    "transitions": [
      {
        "id": "t-pay",
        "from": "pending",
        "event": "pay",
        "to": "paid",
        "conditions": [
          {
            "value": "captured",
            "op": "EQUALS",
            "pointer": "/payment/status"
          }
        ]
      },
      {
        "event": "cancel",
        "to": "cancelled",
        "from": "pending",
        "id": "t-cancel"
      }
    ]
  },
  "currentState": "pending",
  "context": {
    "payment": {
      "status": "captured"
    }
  },
  "event": "pay"
}

{
  "allowed": true,
  "currentState": "pending",
  "event": "pay",
  "terminal": false,
  "nextState": "paid",
  "reasons": [],
  "evaluatedTransitions": 1,
  "matchedTransitionId": "t-pay"
}

{
  "machine": {
    "states": [
      {
        "id": "pending"
      },
      {
        "id": "paid"
      }
    ],
    "transitions": [
      {
        "id": "t-pay",
        "from": "pending",
        "event": "pay",
        "to": "paid",
        "conditions": [
          {
            "value": "captured",
            "op": "EQUALS",
            "pointer": "/payment/status"
          }
        ]
      }
    ]
  },
  "currentState": "pending",
  "context": {
    "payment": {
      "status": "pending"
    }
  },
  "event": "pay"
}

{
  "event": "pay",
  "reasons": [
    {
      "code": "GUARD_FAILED",
      "transitionId": "t-pay",
      "op": "EQUALS",
      "pointer": "/payment/status",
      "message": "The context value at this pointer does not satisfy the condition."
    }
  ],
  "currentState": "pending",
  "terminal": false,
  "evaluatedTransitions": 1,
  "allowed": false
}

Recommended use cases

• Guard an API endpoint that changes a status, before writing anything
• Keep one status policy that several services evaluate identically
• Show a user why an action is unavailable, with the reason rather than a bare 403

Avoid for

• Persisting the new state or emitting events, which stays your call
• Machines whose guards need arbitrary expressions or a rules engine
• Choosing between several allowed transitions — that is ambiguity here, not a priority question

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags