Skip to content

Campaign schema ​

The full YAML → Campaign contract, ported from v1 model.ts. The typed model lives in peregrin-core (Campaign::from_dict, Node::from_dict); expansion passes (include, snippet, discovery) run first in peregrin-loader-yaml. from_dict is total for nodes — bad scalars coerce or drop — but nodes:/events: that aren't arrays are a hard error.

Campaign fields ​

FieldTypeMeaning
namestringCampaign name.
nodes[Node]The graph — see node fields below.
events[EventSchema]Declared event contracts; under strict every entry must compile a payload schema.
functionsmap or [FunctionDefinition]YAML-declared template functions. Map form injects the key as name. Fields: driver, params, capabilities, requires_capability, deterministic, returns.
configmapCampaign config — ${config.*} in templates; also fan_in.count_from source.
include[path]File composition (alias includes).
import[path | {file, as}]Python modules for python-driver handlers.
stop_on[type]Exact-match run terminators.
payload_schemas{type: schema}Per-event-type JSON schemas; *.event.json discoveries fold in here.
capabilitiesmapWorkflow capability policy (secrets, agents, urls, shell/http/python/webhook allow-deny, default_policy).
strictboolStrict validation mode (ADR-0001); JS-truthy parse.
statemapCampaign-level state seed for ${state.*}.
annotationsmapFree-form metadata (ADR-0009).
snippets{name: body}Load-time only — consumed by the expansion pass; never reaches the typed model.
supersedemapQueue policy for trigger events that outpace the executor — key (template over the trigger payload, e.g. "{repo}:{ref}"), mode (latest-wins | fifo), cancel_running (bool). Declared plus an ingress-driver node engages supervisor mode — see Queue & supersede.
runs_on[label]Runner labels this campaign requires (PL-007 fleet scheduling). Every label must appear in the hosting node's advertised capabilities (/api/node, fed by PEREGRIN_RUNNER_LABELS) — AND semantics; empty matches anywhere. Enforced by campaign.start ops, campaign serve hosting, and hub fleet dispatch — see Fleet runners.

Node fields ​

FieldTypeDefaultMeaning
idstring""Unique within the campaign.
driverstring""Registry name (shell, agent, runner, noop, …). Empty driver = pure event node.
handlerstring""Handler reference within the driver.
on[pattern][]Glob subscription — see on: grammar.
emits[type][]Declared output types — strict-checked exact.
modeany | allanyTrigger semantics.
paramsmap{}Driver params — template-resolved at fire time.
max_firesint | "unlimited"1Fire cap. 0/negative/non-integer falls back to the default (v1 quirk, kept — strict rejection is an ADR-0082 fix item). driver: schedule defaults to unlimited.
until[type][]Exact-match stop-listening list.
retire_on[type][]Exact-match retire list — removes the node from the live graph.
retrymap{}max_attempts (default 1), delay secs (default 1), backoff: fixed | linear | exponential. Exhausted → node.failed + DLQ enqueue.
circuit_breakermapnonePresent → breaker armed. threshold (default 5), reset_after secs (default 60), on_trip event type (default circuit.open). Success resets.
pollmap | truthynonePresence flips to poll mode — see normalization below.
fan_inmapnoneCount join over on[0]: count, count_from (config path), emit override.
forward[pattern][]Re-emit each trigger with capture substitution — see Event envelope.
resourcesmap{}weight (min 1) against the run's concurrency gate (cap 50 — inert under the sequential runner, kept for parity).
capabilitiesmap{}Node capability policy — merged over the workflow's (see below). merge: true unions list keys.
statemap{}key — template resolving to a scoped-store key; skip_if — template, truthy (true/yes/1/ok, trimmed, case-insensitive) skips the fire with node.skipped.
annotationsmap{}Free-form metadata.
inputEventSchema (no type)noneParams contract — overrides driver.input.
output{type: EventSchema}{}Per-emitted-type payload contracts; node entries override driver output.

EventSchema ​

{type, fields, schema, annotations} — used by events:, node input:/output:, and driver contracts.

  • fields shorthand: name: <json-type>[?] where ? marks optional; unknown type names compile to string.
  • schema is a full JSON-schema dict and wins over fields when non-empty.
  • Compiled schema checks required properties and per-property primitive type (string/integer/number/boolean/array/ object/null); non-object payloads fail (root).

Load-time normalization ​

Applied by Node::from_dict / the loader expansion, in order:

  1. Discovery — .peregrin/ then .handl/ then the base dir (recursive, dot-dirs skipped; the named roots win name dedupes in scan order — .peregrin is the rebrand name, .handl stays for v1 compatibility): *.node.yml, *.snippet.yml, *.event.json, *.config.yml, *.fn.yml fold into nodes, snippets, payload_schemas, config, functions. *.handler.py, *.secret.yml, .env are discovered for other consumers.
  2. include: — a dict-level key deep-merges file contents under local keys; the top-level include: list does the same per path. ${include(path)} inside strings splices the parsed value (typed when it's the whole string). Circular includes error by path.
  3. snippets: — snippet: <parent> inheritance inside the table resolves to a fixpoint (local wins); snippet: <name> in any dict merges the body under local keys; ${snippet(name)} interpolates like ${include()}. Cycles and non-dict bodies error.
  4. Deep merge — dicts merge per-key local-wins, arrays concatenate local-first, scalars take local.
  5. with: rejection — any node with: key is a hard load error (renamed params, ADR-0025).
  6. Poll normalization — a truthy poll: appends <id>.tick to on and emits, merges poll.until into until, and backfills params.interval from poll.interval.
  7. Schedule normalization — driver: schedule appends <id>.fire to on and <id>.fire + <id>.scheduled to emits (the poll: <id>.tick convention, ADR-0018) and defaults max_fires: unlimited. Each landed <id>.fire re-invokes the driver to arm the next cron occurrence.
  8. Self-trigger default — driver: cli/polling with params.mode != "interval" defaults max_fires: 100 (others: 1; schedule: unlimited).

Coercion quirks kept from v1: scalar strings in list positions iterate into characters (on: start → ["s","t","a","r","t"]) — always write lists; strict, requires_capability, deterministic parse JS-truthy.

Capability merge ​

capabilities merges {...workflow, ...node} for the template ctx and via CapabilityChecker.merge for driver-param checks: node keys override; dict-list keys (shell, http, python, webhook) merge their allow/deny/ports/hosts/paths lists; top-level list keys (secrets, agents, urls) replace — or union when the node sets merge: true. default_policy defaults to deny under strict, allow otherwise.