State Transitions

State Machine Example

Consider an order lifecycle. Orders flow through these states:

Defining States in OpenAPI

States are defined as string enums in your openapi.yaml:

# openapi.yaml
openapi: 3.0.3
info:
  title: Order Management
  version: 1.0.0

components:
  schemas:
    OrderStatus:
      type: string
      enum:
        - draft
        - placed
        - paid
        - shipped
        - delivered
        - cancelled

    Order:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/OrderStatus'
        customerId:
          type: string
      required:
        - id
        - status

The Accept Action

Use <Accept> to validate and apply state transitions. The syntax clearly shows the expected transition:

(* Transition from draft to placed *)
<Accept> the <transition: draft_to_placed> on <order: status>.

(* Transition from placed to paid *)
<Accept> the <transition: placed_to_paid> on <order: status>.

(* Transition from paid to shipped *)
<Accept> the <transition: paid_to_shipped> on <order: status>.

The syntax uses _to_ as the separator because to is a reserved preposition in ARO.

Complete Example

Here's how state transitions work in practice with order management:

(placeOrder: Order Management) {
    <Extract> the <order-id> from the <pathParameters: id>.
    <Retrieve> the <order> from the <order-repository>.

    (* Accept state transition from draft to placed *)
    <Accept> the <transition: draft_to_placed> on <order: status>.

    <Store> the <order> into the <order-repository>.
    <Emit> to <Send Order Confirmation> with <order>.
    <Return> an <OK: status> with <order>.
}

(payOrder: Order Management) {
    <Extract> the <order-id> from the <pathParameters: id>.
    <Retrieve> the <order> from the <order-repository>.

    (* Must be placed to accept payment *)
    <Accept> the <transition: placed_to_paid> on <order: status>.

    <Store> the <order> into the <order-repository>.
    <Return> an <OK: status> with <order>.
}

(shipOrder: Order Management) {
    <Extract> the <order-id> from the <pathParameters: id>.
    <Retrieve> the <order> from the <order-repository>.

    (* Must be paid to ship *)
    <Accept> the <transition: paid_to_shipped> on <order: status>.

    <Store> the <order> into the <order-repository>.
    <Emit> to <Send Shipping Notification> with <order>.
    <Return> an <OK: status> with <order>.
}

Error Handling

If the current state doesn't match the expected state, the runtime throws a clear error:

This follows ARO's "Code Is The Error Message" philosophy. The error tells you exactly what was expected and what was found.

Why This Approach?

Simplicity

No new keywords. No special constructs. Just OpenAPI enums + <Accept>. Use standard control flow (if, match) for complex logic.

Clarity

The transition is explicit in the code. Reading <Accept> the <transition: draft_to_placed> on <order: status> tells you exactly what's happening.

Safety

The runtime validates:

• Current state matches expected from state
• Target state is a valid enum value
• Field exists on the object

State Observers

State observers react to transitions after they occur. Use them for audit logging, notifications, analytics, and side effects.

Observer Pattern

A feature set becomes a state observer when its business activity ends with StateObserver. Add an optional transition filter in angle brackets to observe only specific transitions:

(* Observe ALL status field transitions *)
(Audit Status: status StateObserver) {
    <Extract> the <fromState> from the <transition: fromState>.
    <Extract> the <toState> from the <transition: toState>.
    <Extract> the <orderId> from the <transition: entityId>.
    <Log> the <audit> for the <console>
        with "Order ${orderId}: ${fromState} -> ${toState}".
    <Return> an <OK: status> for the <audit>.
}

(* Observe ONLY draft->placed transition *)
(Notify Placed: status StateObserver<draft_to_placed>) {
    <Extract> the <orderId> from the <transition: entityId>.
    <Log> the <notification> for the <console>
        with "Order ${orderId} has been placed!".
    <Return> an <OK: status> for the <notification>.
}

Transition Data

Observers access transition information via the <transition> object:

• transition: fieldName - The field that changed (e.g., "status")
• transition: objectName - The object type (e.g., "order")
• transition: fromState - Previous state value
• transition: toState - New state value
• transition: entityId - Entity ID if available
• transition: entity - Full object after transition

Use Cases

• Audit logging - Record all state changes for compliance
• Notifications - Alert customers when orders ship
• Analytics - Track state transition metrics
• Side effects - Trigger downstream processes