Writing data and advancing state

Once a handler has passed its guard, it records data on the entity and moves the entity through its state machine.

Writing data with data_accumulation

data_accumulation writes fields onto the entity. writes is a list, and each item takes one of four forms:

ticket.classified:
  data_accumulation:
    writes:
      - category                              # direct:   payload.category -> entity.category
      - source_field: pri                     # mapped:   payload.pri -> entity.priority
        target_field: priority
      - target_field: source                  # literal:  a constant value
        value: "support"
      - target_field: attempts                # computed: a CEL expression
        expression: "entity.attempts + 1"
    source_event: ticket.classified           # defaults to the triggering event

value and expression are mutually exclusive on one item. The direct and mapped forms read from source_event (the triggering event by default), and that event must declare every field they reference.

The key is value. literal: is not accepted here — that key is used inside action blocks instead.

What you write here persists: a value written by one handler is readable as entity.<field> in later handlers, not just this one. See the execution model for the read/write ordering within a handler.

Advancing state

advances_to moves the entity to another state. The target must be one of the flow’s declared states, and advances_to is the only thing that changes an entity’s state:

ticket.resolution_confirmed:
  advances_to: closed        # a terminal state

Gates

A gate is a named boolean checkpoint on the entity. Gates are separate from ordinary boolean fields because the runtime knows about them: they can be cleared as a set with clear_gates, and they must be declared up front so swarm verify can prove every guard reads a gate somebody sets. sets_gate raises one; a later guard reads it as entity.gates.<name>:

review.completed:
  sets_gate: g_reviewed
  advances_to: approved

publish.requested:
  guard:
    id: must_be_reviewed
    check: "entity.gates.g_reviewed == true"
  advances_to: published

Every gate a node sets must be declared in that node’s gate_state (a map of gate name to its starting value):

doc-node:
  gate_state:
    g_reviewed: false        # declare each gate the node uses
  event_handlers:
    # handlers omitted

To reset, clear_gates: true clears every gate on the entity — it is entity-wide, not scoped to this node. There is no way to clear a single gate. This is how you re-enter a cycle:

resubmission.requested:
  clear_gates: true
  advances_to: draft

A complete flow: declare, set, guard, clear a gate

A doc that must be reviewed before it can publish. The gate is declared once, set on approval, required by the publish guard, and cleared if changes are requested. This passes swarm verify.

schema.yaml

stages:
  draft:
    initial: true
  in_review: {}
  published:
    terminal: true
pins:
  inputs:
    events: [doc.submitted, review.approved, changes.requested, publish.requested]

entities.yaml

doc:
  doc_id: text
  title: text

nodes.yaml

doc-node:
  gate_state:
    g_reviewed: false              # 1. declare the gate
  event_handlers:
    doc.submitted:
      create_entity: true
      data_accumulation:
        writes: [doc_id, title]
        source_event: doc.submitted
      advances_to: in_review
    review.approved:                # 2. set it
      select_entity: { by: { doc_id: payload.doc_id } }
      sets_gate: g_reviewed
    publish.requested:              # 3. guard on it
      select_entity: { by: { doc_id: payload.doc_id } }
      guard:
        id: must_be_reviewed
        check: "entity.gates.g_reviewed == true"
        on_fail: reject
      advances_to: published
    changes.requested:              # 4. clear it to send the doc back
      select_entity: { by: { doc_id: payload.doc_id } }
      clear_gates: true
      advances_to: draft

What happens: a submitted doc waits in in_review. publish.requested is rejected until review.approved has set g_reviewed, so a doc cannot skip review. If changes.requested arrives, clear_gates drops the gate and sends the doc back to draft, which means it has to be re-approved before it can publish again. (The events declare a swarm.source: external line, omitted here for brevity.)

See Stages, gates, and timers for the model behind stages and gates.

Getting started

Core concepts

Build a flow

Handlers

Patterns

Operating Swarm

Writing data and advancing state

Writing data with data_accumulation

Advancing state

Gates

​Writing data with data_accumulation

​Advancing state

​Gates

Writing data with data_accumulation

Advancing state

Gates