schema.yaml

schema.yaml declares a flow’s public surface: its lifecycle, the pins other flows wire to, and the agent roles it requires.

State machine

map

The entity’s lifecycle stages, each a map entry. Omit stages: entirely for a stateless flow.

Mark the entry stage initial: true and terminal stages terminal: true.
Terminal stages — once an entity reaches one it never leaves: new events for it are rejected and its timers are cancelled.
A stage may also declare timers: that fire when an entity has sat in it too long.

string

singleton (default) or template — one instance per identity value.

string

Template flows only: the scalar identity field (instance: order_id = one instance per order_id). Every selecting input pin must carry a field with this name; the pin’s instance key derives from it.

Pins

Pins are the flow’s public interface. Event pins declare what it accepts and emits; data pins declare which entity fields it reads and writes.

pins:
  inputs:
    events: [order.created]
    reads: [priority]
  outputs:
    events: [order.fulfilled, order.cancelled]
    writes: [status, total]

No two flows may write the same data pin (a boot error). A pin-declared output event routes through the parent package’s connect edges; the receiving flow’s input pin owns instance selection via resolution and carries. The producer never targets recipients; see Events and routing.

Required agents

list

The roles the flow needs. Each entry has role, subscribes_to, emits, and an optional description.

Fulfillment is checked at boot on two conditions: an agent in agents.yaml whose map key matches the role, and whose subscriptions and emit_events cover the declared subscribes_to and emits.

Other fields

object

Variables populated at flow-instance creation via config_from, available to prompts as {{variable}}.

object

For template flows: an event the platform emits once a new instance is fully started.

Example

schema.yaml

stages:
  new:
    initial: true
  validated: {}
  fulfilling: {}
  fulfilled:
    terminal: true
  cancelled:
    terminal: true
pins:
  inputs:
    events: [order.created]
  outputs:
    events: [order.fulfilled, order.cancelled]
required_agents:
  - role: validator-agent
    subscribes_to: [order.created]
    emits: [order.validated]

Retired grammar. The older initial_state/states/terminal_states list grammar still parses, but stages: is the canonical form and the only one stage timers attach to. The older instance: {by:} block and resolution.instance_key are retired and rejected at load.

Contract reference

Language reference

Operations reference

State machine

Pins

Required agents

Other fields

Example

​State machine

​Pins

​Required agents

​Other fields

​Example

State machine

Pins

Required agents

Other fields

Example