Workflows and Stages
Workflows in workflow-engine are built as a sequence of execution groups. Each execution group contains one or more stages.
Durable Steps
A stage checkpoints at its boundary: its output is written once, when execute() returns. Durable steps checkpoint inside a stage. Side effects run inside named steps whose results are stored in a step ledger (the workflow_steps table), and a suspended or crashed stage resumes by re-running execute() from the top with every completed step answered from the ledger instead of executed again.
Execution Model
workflow-engine uses a distributed, database-native execution model built for reliability, self-healing, and low operational overhead.
Kernel and Ports
workflow-engine is designed around a hexagonal (ports-and-adapters) architecture. The core library exposes a pure, stateless Command Kernel that is completely isolated from side effects. It interacts with the outside world strictly through defined interfaces called Ports.
Annotations
workflow-engine (v0.8.0+) features a first-class Annotations API for capturing typed, structured, and queryable facts (provenance) about workflow execution. This is particularly useful for auditing AI-orchestrated decisions: capturing why an agent chose a path, which prompt/model was used, or recording human approvals.
Definition Versioning
A workflow definition changes every time you deploy. Runs do not stop while
Retry, Restart and Rerun
When a run ends badly, operators want one of three things, and they are not