Structure
Flow. A self-contained package of contracts with typed pins. The composition unit. Flow instance. One running copy of a flow. Static flows have one; template flows have many, created at runtime. Entity. A mutable document moving through a flow instance’s staged lifecycle: stage, gates, and typed fields. Declared inentities.yaml.
Stage. A named lifecycle stage, declared in the schema’s stages: map. An entity is in
exactly one at a time; terminal stages are absorbing. Stage timers, decision gates, and joins
attach to stages. (Some runtime surfaces still say state — the expression root is
_entity.current_state; stage is the authored term.)
Pin. A typed input or output of a flow. Output pins bind to input pins through the
package connect block; an input pin’s resolution and carried identity (the identity field
the event carries) select the receiving instance — see
Events and routing.
Pack. A declarative integration bundle. Provider trigger packs turn webhooks into typed
normalized events; connector packs turn provider APIs into declared tools; channel packs
render decision cards (Telegram ships first).
Bundle. The set of contract files loaded together, identified by a content hash.
Execution
System node. Deterministic code that subscribes to events, runs a handler, advances stages, and emits events. No LLM. Agent. An LLM session that subscribes to events, reasons, calls tools, and emits events. Handler. The unit of execution attached to an event on a system node. Runs as a dependency graph and commits atomically. Event. A typed message with a payload schema. The only communication primitive. Envelope. The standard fields every event carries (event_id, run_id, entity_id,
source) — distinct from your payload fields.
Run. A top-level execution context. Correlates events, deliveries, sessions, and turns by
run_id.
Session. An agent’s execution context. With memory: false (the default) it lasts one
task; with memory: true it is one durable conversation per (run, agent, flow instance).
Conversation. The API’s name for a session’s recorded transcript. The conversation.*
methods read sessions, their turns, and transcripts.
Directive. An operator message sent into a running agent’s session
(swarm agent directive) — steering, not state: it changes no entity data.
Model alias. The provider-agnostic tier an agent declares (cheap, regular,
frontier), resolved to a concrete model per backend by llm.models.
State & convergence
Gate. A named boolean on an entity, set bysets_gate and checked by guards.
Decision gate. A stage-owned typed decision (stages.<stage>.gate): the stage waits for
a human verdict, every outcome is declared, and the card’s content hash protects against
deciding on stale facts.
Decision card. The typed resource a decision gate (or an activity approval) creates:
context, possible verdicts, required input fields. Channels render it; one API commits it.
Join. A declared barrier in a stage: which arrivals complete a fan-out (members, window),
with dedup and timeout owned by the platform.
Fan-out. A handler row emitting one event per item of a list; each event typically
resolves into its own template-flow instance.
Accumulator. An append-only list on an entity (record_evidence, accumulate) used for
histories and aggregation — distinct from fields, which overwrite.
Timer. A durable, time-based trigger that fires an event into the loop.
Workspace. An agent’s isolated filesystem (/workspace plus read-only mounts), scoped
per agent or per flow instance by its workspace class.
Operations
Mailbox. The durable human-in-the-loop task queue. Decisions are approve, reject, defer. Mutation log. The per-field before-and-after record of entity changes (entity_mutations),
the basis for the flight recorder and fork.
Flight recorder. Events, mutations, agent turns, and deliveries joined on run_id to
reconstruct a run.
Replay. Redelivering a persisted event to its subscribers.
Fork. Reconstructing system state at a moment in time and resuming, optionally against new
contracts.
Dead letter. Where an event lands after retry exhaustion, a target-resolution failure, or
chain-depth overflow.
Static analyzer. The boot-time and swarm verify checks that validate a bundle against
the platform specification.
Policy. Named configuration values referenced as policy.* and {{variable}}.
Permission. A named capability an agent must hold to call a platform tool (granted
directly or through a permissions_bundle in policy). See Tools.
CEL. Common Expression Language. Strongly typed and non-Turing-complete; used for all
guards, rules, and filters.
Flow scope key. A flow’s semantic namespace by position in the tree. Stable across
instances. Distinct from the flow instance path.