Execution Runtime

The execution runtime is responsible for running workflows. It provides deterministic, observable execution across connected systems. The runtime operates asynchronously and ensures every workflow run is fully recorded before execution begins.

---

Components

API layer — receives workflow triggers (user actions, scheduled events, API calls). Performs authentication, creates a WorkflowRun record, and enqueues the job. No workflow logic runs in the API layer.

Worker runtime — an ARQ worker that processes jobs from the Redis queue. Executes steps sequentially, updates run state, and persists step outputs. Workers are stateless between runs and scale horizontally.

Job queue — Redis broker with ARQ. Distributes jobs across workers. Allows workflows to execute asynchronously and scale without coupling to the HTTP layer.

Database ledger — all workflow state is persisted in PostgreSQL. Every WorkflowRun, TaskRun, and ChunkRun is committed frequently so execution progress is always observable.

---

Execution lifecycle

Trigger (user action / schedule / API)
  ↓
Pre-flight commit
  WorkflowRun created (PENDING)
  TaskRun rows created for every step
  ↓
Enqueue → Redis
  ↓
Worker picks up job
  ↓
Step execution loop:
  mark TaskRun RUNNING
  execute verb
  persist result
  mark TaskRun SUCCEEDED
  ↓
WorkflowRun marked SUCCEEDED / FAILED / CANCELLED

The pre-flight commit is a non-negotiable invariant: if the run record doesn’t exist in the database, the workflow cannot execute.

---

Dispatch modes

Mode	Description
AtomicOp	Single task executed sequentially
WorkflowRef	Nested workflow — calls another workflow inline
ChunkedDispatch	Fan-out — spawns one ChunkRun per generator record

ChunkedDispatch allows large datasets to be processed concurrently. Each chunk has an isolated execution context.

---

Suspension

Some workflows require human approval before proceeding. When a GOVERN step returns a suspension signal:

1. The workflow pauses at that step
2. State is persisted
3. An approval request is created
4. Execution resumes only after approval is granted by an authorized user

---

Cancellation

Workflows can be cancelled while running. When cancellation occurs:

• remaining steps are skipped
• the WorkflowRun is marked CANCELLED

External system changes made by steps that already completed are not automatically rolled back. Design workflows with idempotency in mind.

---

Runtime guarantees

• Deterministic execution order — steps always execute in definition order
• Persistent state — every state transition is committed to the database
• Explicit failure — failures are logged and scoped; no silent retries
• Observable behavior — every run produces a complete audit trail

These guarantees allow complex enterprise workflows to run safely across multiple systems.