Event Keywords

Keywords for defining and handling events.

on

Defines an internal event handler.

on :payment_success from @payment
  order moves to #paid

Internal events can only be triggered by other machines.

on ... (api)

Defines a public/API event handler.

on :checkout from @customer (api)
  order moves to #processing

The (api) suffix marks the event as externally accessible (e.g., via HTTP).

on ... (queued api)

Defines an API event that processes asynchronously via queue.

on :generate_report from @user (queued api)
  // Returns 202 immediately, processes in background
  generate report

The queued modifier:

1. Validates event synchronously
2. Queues the validated event
3. Returns response immediately (typically 202)
4. Processes event asynchronously

See Event Queues.

on ... (priority ...)

Sets priority level for event processing.

on :checkout from @customer (api) (priority high)
  order moves to #processing

on :analytics from @system (priority low)
  log analytics data

Priority levels: critical, high, normal (default), low, bulk.

Requires strategy: priority in queue configuration.

from

Specifies the sender of an event.

on :payment_success from @payment
  // Only handles events from @payment

Optional - without from, accepts from any sender:

on :status_update
  // Accepts from any source

emit

Sends an event to another machine synchronously (waits for result).

emit :payment_request to @payment

Capture the result:

$payment becomes emit :payment_request to @payment

? $payment.success
  order moves to #paid

emit async

Sends an event to another machine asynchronously (via queue, doesn't wait).

emit async :payment_request to @payment
emit async :analytics_event to @analytics

The event is queued and processed in the background. See Event Queues.

to

Specifies the target of an emitted event.

emit :notification to @customer

all

Broadcasts an event to all instances of a machine.

emit :reminder to all @order

Used with emit and to. Can be combined with state filtering using in:

emit :reminder to all @order in #pending

See Broadcasting Events for full documentation.

in (broadcast context)

Filters broadcast recipients by state.

// Single state
emit :alert to all @order in #pending

// Multiple states
emit :alert to all @order in #pending, #processing

with / with:

Attaches data to an emitted event.

Inline:

emit :payment_request to @payment
  with $order_id, $total

Table format:

emit :order_details to @warehouse
  with:
    | field    | value      |
    | order_id | $order_id  |
    | items    | $items     |

With validation:

emit :checkout to @order with:
  | field    | value     | validation                       |
  | order_id | $order_id | required, string, valid uuid     |
  | email    | $email    | required, string, valid email    |
  | total    | $total    | required, number, greater than 0 |
  | coupon   | $coupon   | optional, string                 |

The validation column is optional. Rules are comma-separated. See Data Validation.

messages:

Defines custom error messages for validation rules. Used after a with: table.

emit :register to @user with:
  | field    | value  | validation                    |
  | email    | $email | required, string, valid email |
  | password | $pass  | required, string, min 8 chars |

  messages:
    email.required: "Email address is required"
    email.valid email: "Please enter a valid email"
    password.min 8 chars: "Password must be at least 8 characters"

Message keys use field.rule format. Available placeholders: {field}, {value}, {min}, {max}, {rule}.

Validation Events

:validation_failed

Automatically emitted when event data validation fails.

on :validation_failed
  emit :error to @customer with:
    | field  | value   |
    | errors | $errors |

Payload includes: event, source, failed_rules, summary.

:constraint_violated

Automatically emitted when a context constraint is violated. The action is rolled back.

on :constraint_violated
  ? $field is "$retry_count"
    emit :max_retries to @customer

Payload includes: field, old_value, new_value, rule, message.

Response Keywords

reply

Returns a structured response to API callers.

on :checkout from @customer (api)
  order moves to #awaiting_payment

  reply 201 with:
    | id     | $order_id     |
    | status | current_state |

reply ... with:

Defines the response body using a field mapping table.

reply 200 with:
  | field        | from          |
  | id           | $order_id     |
  | customer.name| $customer_name|
  | total        | $total        |

reply STATUS MEANING with:

Human-readable HTTP status for clarity:

reply 400 bad request with:
  | error   | "CART_EMPTY" |
  | message | "Cannot checkout with empty cart" |

reply ... async for

Returns an immediate async response with callback tracking.

reply 202 async for :generate_report:
  | report_id | $report_id |
  | status    | "queued"   |

Options: callback:, channel:, url:

send callback for

Sends the async completion callback to the original caller.

on :report_compiled
  report moves to #ready

  send callback for :generate_report:
    | report_id | $report_id  |
    | status    | "completed" |

response:

Defines a reusable named response at machine level.

machine: @order

response: order_created
  | field  | from          |
  | id     | $order_id     |
  | status | current_state |

on :checkout from @customer (api)
  reply 201 with order_created

Scheduled Events

triggered:

Specifies when a scheduled event should fire.

on :cleanup
  triggered: every day at 00:00

  for each item in #expired
    delete item

Schedule patterns:

triggered: every day at 00:00
triggered: every hour
triggered: every monday at 09:00
triggered: every 30 minutes
triggered: every month on 1st at 00:00

for each

Iterates over aggregates. Required with triggered:.

on :send_reminders
  triggered: every day at 09:00

  for each order in #pending
    ? created more than 12 hours ago
      emit :reminder to @customer

Can target multiple states:

for each order in #pending, #processing
  send status update

Queue Configuration

queue:

Configures event queue behavior at system or machine level.

system: e-commerce

queue:
  strategy: fifo
  concurrency: 10
  timeout: 30 seconds

Machine-level overrides system defaults:

machine: @order

queue:
  concurrency: 5
  timeout: 60 seconds

Queue Options

Option	Type	Default	Description
strategy	fifo | priority	fifo	Processing order
concurrency	number	10	Max parallel instances
timeout	duration	30 seconds	Per-event timeout

retry:

Configures automatic retry for failed events.

queue:
  retry:
    max_attempts: 3
    backoff: exponential
    initial_delay: 1 second
    max_delay: 5 minutes

Option	Type	Default	Description
max_attempts	number	3	Maximum retry attempts
backoff	linear | exponential	exponential	Delay strategy
initial_delay	duration	1 second	First retry delay
max_delay	duration	5 minutes	Maximum delay cap

dead_letter:

Configures Dead Letter Queue for failed events.

queue:
  dead_letter:
    enabled: true
    retention: 7 days

Option	Type	Default	Description
enabled	boolean	true	Enable DLQ
retention	duration	7 days	How long to keep failed events

alerts:

Configures alerting thresholds.

queue:
  alerts:
    pending_warning: 100
    pending_critical: 500
    dlq_warning: 10
    dlq_critical: 50

See Event Queues Guide for complete documentation.