Handlers

The mental model

Think of a handler as a small state machine, not as a function that runs once and disappears. An authored handler starts when a token arrives at its arrivalPortId. Actions run top to bottom. A call or await stores the next action index; the matching return schedules a resume in the same handler. Arespond sends a payload back through a response path, and a fail enters the failure path.

sequenceDiagram
  participant C as Caller
  participant S as Service
  participant D as Dependency
  C->>S: arrival on an input port
  S->>D: call (current payload)
  Note over S: handler pauses
  D-->>S: matching return edge
  Note over S: resume next action in the same handler
  S-->>C: respondTo: arrival

Where handlers live

Select a component and open the Behavior tab. TheArrival handlers section shows one handler per input port. A graph must keep exactly one handler for every input port; a newly created component receives empty catalog_default bindings. Adding or editing actions changes the handler origin to authored. A migrated_review binding is a warning that the persisted behavior needs confirmation.

The eight handler actions

These are the current HandlerActionKind values. The web editor’s action picker exposes every kind except for_each; imported or agent-authored for_each actions still render their collection and item fields and are validated and simulated by the same runtime.

{
  "id": "ask-inventory",
  "kind": "call",
  "edgeId": "inventory-request",
  "awaitPortId": "stockResponseIn"
}

{
  "id": "wait-for-payment",
  "kind": "await",
  "interactionId": "payment-request",
  "resumePortId": "paymentResponseIn"
}

{
  "id": "keep-order-shape",
  "kind": "map",
  "mapping": "identity"
}

{
  "id": "send-items",
  "kind": "for_each",
  "collection": {
    "expressionVersion": "expression.v1",
    "source": "payload",
    "pointer": "/items"
  },
  "itemVariable": "item",
  "edgeId": "item-worker",
  "maxItems": 50,
  "mode": "serial"
}

{
  "id": "notify-shipping",
  "kind": "emit",
  "edgeId": "shipping-event"
}

{
  "id": "reply-to-checkout",
  "kind": "respond",
  "respondTo": "arrival"
}

{
  "id": "reject-order",
  "kind": "fail",
  "code": "invalid_address",
  "edgeId": "error-out"
}

{
  "id": "mark-ready",
  "kind": "assign",
  "assignments": [
    { "pointer": "/status", "value": "ready" },
    { "pointer": "/attempts", "value": 1 }
  ]
}

Edge-backed actions select stable graph edges, not labels typed into the action. The allowed edge kinds are intentionally narrow: calls use synchronous request or data-access request/write edges; emits and iterations use asynchronous message, event publish, control, or write data-access edges; responses use synchronous response, response-role data-access, ACK, or NACK edges; failures use error edges.

Action fields in detail

Payloads, pointers, and value references

A handler has two useful payload views. payload is the current value and can change after an assign or a returned call payload. input is the immutable payload captured when the handler first received the arrival; it remains available through calls, awaits, retries, and catches. This is why a post-call guard can compare the returned payload with the original request.

Pointers use RFC 6901 syntax. An empty pointer reads or replaces the whole value. A path such as /order/items/0 traverses existing object members and numeric array indexes; ~1 represents / inside a key and ~0 represents ~.

{
  "id": "mark-ready",
  "kind": "assign",
  "assignments": [
    { "pointer": "/status", "value": "ready" },
    { "pointer": "/items/0/approved", "value": true }
  ]
}

A for_each value reference must resolve to an array. Each child payload starts from the parent object with a payload-selected collection removed when the reference is a payload path, then adds/itemVariable and /iterationIndex. An empty collection completes the parent without dispatching children.

A worked request handler

This fragment keeps the useful checkout mental model from the original guide, while showing the exact authored fields. The edge IDs must already exist on the graph, and the response edge must be paired by its interaction identity.

{
  "arrivalPortId": "requestIn",
  "origin": "authored",
  "actions": [
    { "id": "mark-checking", "kind": "assign", "assignments": [{ "pointer": "/status", "value": "checking" }] },
    { "id": "authorize", "kind": "call", "edgeId": "auth-request", "awaitPortId": "responseIn" },
    { "id": "fulfill", "kind": "emit", "edgeId": "fulfillment-queue" },
    { "id": "reply", "kind": "respond", "respondTo": "arrival" }
  ]
}

Order matters: the assignment changes the payload used by the call, the call waits for its matching return, the emit does not wait, and the arrival response uses the original caller route. If the call fails, a matching catch can recover before the response completes.

Handlers versus component settings

The Behavior tab also contains component settings such as cache TTL, service duration, queue attempts, or an external dependency outcome. Settings describe intrinsic component behavior; handlers describe what the component does when a token arrives. Connections provide the routes that edge-backed actions are allowed to use. A simulation is the combination of all three.

Conditions and edge matching

Add Run only when… to an action to attach an expression.v1 HandlerCondition. Choose all or any; a false action guard skips only that action and the list continues. Equality is structural JSON equality, so object key order does not change a match. A missing path makes equals and not_equals false; use exists or not_exists when absence is the condition you mean.

"when": {
  "expressionVersion": "expression.v1",
  "match": "all",
  "clauses": [
    { "source": "payload", "pointer": "/status", "operator": "equals", "value": "ready" },
    { "source": "fixture", "fixtureNodeId": "session-cache", "pointer": "/enabled", "operator": "exists" }
  ]
}

Edge matching is a separate feature. GraphEdge.when uses expression.v2 and is valid only on a Topic’s deliverOut subscription edge. It adds contains, which is true only when the selected value is an array containing a canonically equal member. When a topic publishes, each subscription edge is evaluated independently; selected edges are delivered and unselected edges are skipped.

"when": {
  "expressionVersion": "expression.v2",
  "match": "all",
  "clauses": [
    { "source": "payload", "pointer": "/channels", "operator": "contains", "value": "email" }
  ]
}

Arrival, return, and completion semantics

An input arrival starts one handler. A call sends a request and saves the next action index. A return edge is matched by interaction identity, reverse endpoints, edge kind, and return-port role; the handler on that return port is not invoked for the matched return. Instead, the original handler resumes at the next action with the returned payload and the original input still available.

Failure handling and catches

A fail action stops the current action list. If its optional edgeId points to an error edge, the failure is routed explicitly. Otherwise the simulator creates a failed invocation outcome. Interaction resilience can retry timeout, network_error, http_429, or http_5xx outcomes on a synchronous interaction, subject to that interaction’s maxAttempts and backoff policy. After retries are exhausted, the runtime searches catches from first to last.

A matching catch unwinds the failed call frames, runs its recovery actions, and records ERROR_HANDLED. An unmatched failure propagates through waiting call frames; if no caller catch handles it, the token fails. A catch-all has no when and must be the final catch clause.

{
  "id": "recover-timeout",
  "when": {
    "expressionVersion": "expression.v1",
    "match": "all",
    "clauses": [
      { "source": "arrival", "pointer": "/code", "operator": "equals", "value": "dependency_timeout" }
    ]
  },
  "actions": [
    { "id": "mark-degraded", "kind": "assign", "assignments": [{ "pointer": "/status", "value": "degraded" }] }
  ],
  "completion": { "edgeId": "fallback-response", "outcome": "degraded" }
}

What to look for in a run

The run artifact records decisions and effects in deterministic order. Use the action or edge ID in event details to connect an authored field to the run-time evidence.

Ordering and limits

Action order is the authored array order. The compiler keeps edge dispatch deterministic by ascending priority, then edge ID. A condition can skip an action, but it cannot reorder later actions. Calls and awaits create suspension points; for_each is the only action that must be terminal.

Troubleshooting validation and runs

The editor shows handler diagnostics with a source path and remediation. Fix the graph diagnostic before interpreting a run failure; compile-time errors mean the action was never executable.