Field index

This page is a navigation index, not the field spec. For the per-page reference of a contract surface follow the linked page; for binding authority see platform-spec.yaml. For the handler pipeline ordering, see Handler fields.

By question

You want to	Page
Block a handler unless a condition holds	Guards
Choose what happens when a guard fails (`on_fail`)	Guards → on_fail
Write payload fields onto the entity (`data_accumulation`)	Writing data and advancing state
Move the entity to another state (`advances_to`)	Writing data and advancing state
Raise or check a gate (`sets_gate` / `clear_gates`)	Writing data and advancing state
Emit an event with a payload (`emit`)	Emitting
Branch by payload condition (`rules`) or by accumulator result (`on_complete`)	Branching
Acquire an entity (`create_entity` / `select_entity` / `select_or_create_entity`)	Entity acquisition
Wait for multiple events to arrive (`accumulate`)	Accumulation
Invoke a platform action (`action`)	Actions
Open a mailbox item for a human (`action.mailbox_write`)	Actions → mailbox_write
Commit files into the artifact repo (`action.artifact_repo_commit`)	Actions → artifact_repo_commit
Schedule a durable timer (`timers`)	nodes.yaml → Timers
Declare a system node	nodes.yaml
Declare an agent and its prompts	agents.yaml
Declare an entity type and its fields	entities.yaml
Declare an event schema	events.yaml
Declare a flow’s state machine and pins	schema.yaml
Declare workspace classes and permission bundles	policy.yaml
Declare a shared type, enum, or list	types.yaml
Subscribe to a platform-emitted event (e.g. `mailbox.item_decided`)	Human in the loop → Decisions
Write a CEL expression in a guard, rule, filter, or emit	Expressions (CEL)

Fields by file

Top-level fields per contract file. Sub-field detail lives on the linked reference page.

`package.yaml`

Field	Required	One line
`name`	yes	Flow identifier; unique within the bundle.
`version`	yes	Semantic version of the flow.
`description`	yes	One-line human description.
`platform_version`	yes	Range the flow targets (e.g. `">=0.7.0 <0.8.0"`).
`flows`	yes	List of child flow ids (empty list `[]` for leaf flows).

Reference.

`schema.yaml`

Field	Required	One line
`stages`	yes*	Map of the entity’s lifecycle stages; mark one `initial: true` and terminal ones `terminal: true`. Omit entirely for a stateless flow.
`mode`		`singleton` (default) or `template` (one instance per identity value).
`instance`	template only	Scalar identity field: `instance: order_id` means one instance per order_id.
`pins.inputs.events`		Events that enter this flow from outside.
`pins.outputs.events`		Events this flow emits to consumers outside it.

Reference.

`entities.yaml`

A map of <entity_type>: { <field>: <declaration>, ... }. Each field declaration is either a short form (field_name: type) or a verbose block.

Sub-field	One line
`type`	One of the built-in scalars or a named type. See types.yaml.
`initial`	Default value when no writer fills the field. Required when no writer or `_unused_reason` exists.
`immutable`	If `true`, only the first writer succeeds.
`materialize_from`	Project a node accumulator into an entity field. See Accumulation → materialize_from.
`_unused_reason`	Suppress the writer-coverage advisory for a field with no writer.
`_unused_reader_reason`	Suppress the reader-coverage advisory for a field only external tools read.
`description`	Human annotation.

Reference.

`events.yaml`

A map of <event.name>: { <field>: <type>, ..., swarm: { ... } }. Fields under the event name declare the payload schema; the swarm: sub-block declares routing/lifecycle hints.

Sub-field	One line
`swarm.source: external`	The event originates outside the flow; the analyzer should not look for an internal producer.
`swarm.consumer: external`	The event is emitted for external consumers; the analyzer should not require an internal subscriber.

Reference.

`nodes.yaml`

A map of <node-id>: { ... }.

Field	One line
`id`	Node identifier; must match the map key.
`execution_type`	Derived (`system_node`); explicit form accepted, carries no information.
`subscribes_to`	List of events this node handles.
`produces`	List of events this node emits (analyzer-checked).
`event_handlers`	Map of event → handler block. See Handler fields.
`timers`	Durable timers attached to this node. See Timers.
`gate_state`	Declares the gates this node sets, with their starting values.
`permissions`	Platform permissions this node requires (e.g. `create_flow_instance`).

Reference.

`agents.yaml`

A map of <agent-role>: { ... }. The role key must match a role declared in schema.yaml.

Field	One line
`model`	Alias (`cheap`, `regular`, `frontier`) resolved by `llm.models` per backend.
`subscriptions`	List of events the agent receives.
`emit_events`	List of events the agent may emit (analyzer-checked).
`memory`	`false` (default): fresh conversation per task. `true`: one durable conversation per flow instance (scope derived from the flow’s instance model).
`max_turns_per_task`	Turn cap per task.
`workspace_class`	Named workspace from `policy.yaml`. See Agent workspaces.
`permissions_bundle`	Named permission set from `policy.yaml`.
`prompt_ref`	Optional explicit prompt reference; by default the agent loads `prompts/<role>.md`.

Reference.

`tools.yaml`

A map of <tool-name>: { ... } declaring tools agents may call. See tools.yaml reference.

`policy.yaml`

Flow-level thresholds, workspace classes, permission bundles. See policy reference.

`types.yaml`

Shared named types, enums, and lists. See types.yaml.

Sub-field value vocabularies

Enumerable value lists, kept here so search finds them.

`guard.on_fail` values

Value	Trace outcome	What happens
`reject` (default)	`reject`	Stop; no side effects; entity unchanged.
`discard`	`discard`	Drop silently; no failure record.
`kill`	`kill`	Advance the entity to a terminal state.
`escalate:{event}`	`escalate`	Emit the named event instead of proceeding.

Detail: Guards → on_fail.

`timer.start_on` and `timer.cancel_on` forms

Form	`start_on`	`cancel_on`	Meaning
`state:<name>`	✓	✓	Fires when the entity enters the named state.
`event:<name>`	✓	✓	Fires when the named event is delivered for the entity.
`boot`	✓	✗	Fires once at platform startup (typically paired with `recurring: true`).

Bare strings are boot errors. Detail: Timers.

`data_accumulation.writes` forms

Form	Shape	Meaning
Direct	`field_name`	`payload.field_name → entity.field_name`.
Mapped	`{source_field, target_field}`	Renamed mapping from payload to entity.
Literal	`{target_field, value}`	Write a constant; no expression evaluation.
Computed	`{target_field, expression}`	CEL expression against handler context.

value and expression are mutually exclusive on one item. The literal key is value, not literal. Detail: Writing data and advancing state.

`action.id` catalog

Action id	Required sibling	Purpose
`create_flow_instance`	`template`, `instance_id_from`, `config_from`	Spawn a child flow instance from this handler.
`record_evidence`	`evidence_target` (defaults to node id)	Append the payload to a node accumulator buffer.
`mailbox_write`	`mailbox` (object)	Materialize a human-in-the-loop mailbox row.
`artifact_repo_commit`	`artifact_repo` (object)	Commit allowlisted files into a local git artifact repo; exposes `swarm-artifact://` URL.

Detail: Actions. Authoring product-specific actions is not supported.

`agent.memory` values

Value	Meaning
`false`	A fresh conversation per task; no memory across events. The default.
`true`	One durable conversation per (run, agent, flow instance); requires a flow with per-instance identity.

The older conversation_mode/session_scope fields are retired and rejected at load. Detail: agents.yaml.

Handler outcomes (what you see in `swarm run trace`)

Outcome	Meaning
`success`, `reject`, `discard`, `kill`, `escalate`	Guard-related; see the `on_fail` values above.
`dead_letter`	Delivery exhaustion after retries.
`terminal_reject`	An event aimed at an entity already in a terminal state.
`waiting`, `fanned_out`	Intermediate states for `accumulate` and fan-out.

Detail: Execution model.

When in doubt

platform-spec.yaml is authoritative — if this page disagrees with it, the spec wins.

Contract reference

Language reference

Operations reference

By question

Fields by file

`package.yaml`

`schema.yaml`

`entities.yaml`

`events.yaml`

`nodes.yaml`

`agents.yaml`

`tools.yaml`

`policy.yaml`

`types.yaml`

Sub-field value vocabularies

`guard.on_fail` values

`timer.start_on` and `timer.cancel_on` forms

`data_accumulation.writes` forms

`action.id` catalog

`agent.memory` values

Handler outcomes (what you see in `swarm run trace`)

When in doubt

​By question

​Fields by file

​package.yaml

​schema.yaml

​entities.yaml

​events.yaml

​nodes.yaml

​agents.yaml

​tools.yaml

​policy.yaml

​types.yaml

​Sub-field value vocabularies

​guard.on_fail values

​timer.start_on and timer.cancel_on forms

​data_accumulation.writes forms

​action.id catalog

​agent.memory values

​Handler outcomes (what you see in swarm run trace)

​When in doubt

By question

Fields by file

`package.yaml`

`schema.yaml`

`entities.yaml`

`events.yaml`

`nodes.yaml`

`agents.yaml`

`tools.yaml`

`policy.yaml`

`types.yaml`

Sub-field value vocabularies

`guard.on_fail` values

`timer.start_on` and `timer.cancel_on` forms

`data_accumulation.writes` forms

`action.id` catalog

`agent.memory` values

Handler outcomes (what you see in `swarm run trace`)

When in doubt