Explanation
Why peregrin is designed the way it is — the concepts behind the contracts in Reference.
Orientation
- Architecture — nodes, hub, the sepia boundary, planes, where peregrin sits in the org.
- Concepts — the domain vocabulary, defined once.
- Boundaries — owns / doesn't-own, neighbors named.
- Decisions — ADR-lite: decision → alternative → consequence.
The model
- Abstraction via event types — why events are the interface.
- Event graph model — why the engine uses an event graph, not a DAG.
- Events — the role of events as flow and state.
- Drivers — what drivers are and how the unified registry works.
- Self-modifying workflows — how the graph changes at runtime.
The seams
- Adapter ports — persistence and observability as swappable ports.
- Observers — the observability port.
- Stores — the persistence port.
- Include and snippet resolution — how fragments compose.
- Plugins — why YAML files are plugins, and how bundles distribute them.
The bounds
- Resilience — retry, DLQ, circuit breaker.
- Loop protection — the mechanisms that bound a run.
- Safety — how the engine keeps AI-governed workflows safe.
- Threat model — who trusts whom, and what happens when trust is wrong.
The whole
- Architecture — nodes, hub, the sepia boundary, planes.