Events
Events are the unit of flow and state. Every event is a flat envelope — type, payload, source, id, ts — and the append-only log the bus keeps IS the workflow state. The full contract, including the engine-synthetic table (start, workflow.done, node.failed, capability.violation, …), is specified in Event envelope; this page is about the why.
Events are the state
Because the log is append-only and every action is recorded, the entire run state can be reconstructed by replaying it. That is what makes the run inspectable (peregrin campaign run prints the log, --history persists it), resumable (--replay seeds a run from a prior log and check_ready picks up subscriptions that were already satisfied), and debuggable (peregrin runs/explain/log read the durable log back).
Two consequences worth internalizing:
- Run-scoped data rides in
payload. The envelope is closed — five fields, no more. Repo/sha/ref metadata, state keys, fan-in collections: all payload. There is no hidden channel. - Nothing secret, ever. The log is the shareable artifact; secrets reach nodes through the run's secrets record and the
capabilities.secretsgate, never through an event.
Custom events
Custom events are just strings. No registration is required.
Naming convention
Dot-separated, hierarchical: pr.approved, deploy.success, shard.3.done.
This is what makes wildcards work: on: [pr.*] catches pr.approved, pr.rejected, anything with one trailing segment; on: [pr.**] catches the whole pr. subtree. Captured segments are addressable in templates as ${event.match.N} — which is how conventions like push.gated.<repo>.<clone_url>.<sha> put payload-shaped data into the type itself (the typed-routing idiom (ci-ingress/docs-deploy use it)). See on: event patterns.
Emitting
A node's emits: list declares its output types; under strict: true every event a node produces must literally appear there. Where the events actually come from — the returned Vec<Event>, params.emit rc-mapping, ctx.emit, forward: re-emission, and the ingress channel — is specified in Event envelope § Emission contract.
- id: review
driver: shell
on: [pr.opened]
emits: [pr.approved, pr.changes_requested]
params:
cmd: "review.sh '${event.payload.url}'"
emit:
"0": pr.approved
default: pr.changes_requestedThe engine's own events
Engine-synthetic events (source: "__runner__", or the affected node id for node.* types) are exempt from payload-schema validation and subscribable like any other type — a node can react to node.failed, node.exhausted, circuit.open, or workflow.cancelled with the same on: machinery as domain events. Failure handling is not a side channel; it is more graph.
See also
- Event envelope — fields, synthetic types, emission contract
on:event patterns — matching, captures,mode/fan_in- Event graph model — why events are the topology