Skip to content
Wovyr

Workflow Engine Overview

Document ID: WF-001 Version: 1.0.0 Status: Draft Owner: Workflow Engine Team Last Updated: 2026-06-26

1. Purpose

Section titled “1. Purpose”

The Workflow Engine is the core orchestration runtime of the Wovyr AI Platform.

It is responsible for executing durable, long-running, event-driven workflows that coordinate:

  • AI model inference
  • Tool execution
  • Human interactions
  • External service calls
  • Timers and schedules
  • Parallel execution
  • State management
  • Recovery and replay

The engine provides deterministic orchestration while allowing controlled interaction with non-deterministic systems such as LLMs.

2. Objectives

Section titled “2. Objectives”

The Workflow Engine is designed to provide:

  • Durable execution
  • Deterministic orchestration
  • Horizontal scalability
  • Long-running workflow support
  • Event-driven execution
  • Failure recovery
  • Replay capability
  • High observability
  • Extensibility

3. Design Principles

Section titled “3. Design Principles”

The engine follows these principles:

  1. Durable by default
  2. Event-driven execution
  3. Deterministic state transitions
  4. Explicit side effects
  5. Idempotent activity execution
  6. Checkpoint-based recovery
  7. Versioned workflow definitions
  8. Pluggable activity implementations

4. Responsibilities

Section titled “4. Responsibilities”

The Workflow Engine is responsible for:

  • Parsing workflow definitions
  • Building execution graphs
  • Scheduling work
  • Executing activities
  • Managing workflow state
  • Handling retries
  • Coordinating compensation
  • Persisting execution progress
  • Publishing lifecycle events
  • Supporting replay and recovery

The engine is not responsible for business logic inside activities.

5. Supported Workflow Types

Section titled “5. Supported Workflow Types”

Sequential

Section titled “Sequential”

Activities execute one after another.

Example:

Start
  │
  ▼
Validate Input
  │
  ▼
Generate Prompt
  │
  ▼
Invoke LLM
  │
  ▼
Store Result
  │
  ▼
End

Parallel

Section titled “Parallel”

Multiple branches execute concurrently.

         Start
           │
     ┌─────┴─────┐
     ▼           ▼
 Activity A   Activity B
     └─────┬─────┘
           ▼
         Merge
           │
           ▼
          End

Conditional

Section titled “Conditional”

Execution path depends on workflow state or activity results.

Supported constructs:

  • If / Else
  • Switch
  • Pattern matching

Event-Driven

Section titled “Event-Driven”

Execution pauses until an external event is received.

Examples:

  • Payment received
  • Human approval
  • Webhook callback
  • File uploaded

Scheduled

Section titled “Scheduled”

Execution starts based on:

  • Cron expression
  • Fixed interval
  • One-time schedule
  • Calendar trigger

AI-Orchestrated

Section titled “AI-Orchestrated”

AI activities participate as first-class workflow steps.

Examples:

  • Prompt generation
  • Summarization
  • Classification
  • Code generation
  • Decision support

AI outputs are treated as activity results and persisted like any other activity.

6. Core Concepts

Section titled “6. Core Concepts”

Workflow Definition

Section titled “Workflow Definition”

A versioned blueprint describing activities, transitions, and policies.

Workflow Instance

Section titled “Workflow Instance”

A running execution created from a workflow definition.

Each instance has:

  • Unique ID
  • Current state
  • Variables
  • History
  • Metadata

Activity

Section titled “Activity”

The smallest executable unit.

Examples:

  • HTTP call
  • Rust function
  • AI inference
  • Database operation
  • Human task
  • Timer
  • Tool invocation

Activities are isolated and independently retryable.

Execution Context

Section titled “Execution Context”

Contains runtime information:

  • Variables
  • Inputs
  • Outputs
  • Correlation ID
  • Execution metadata
  • Security context

7. Workflow Lifecycle

Section titled “7. Workflow Lifecycle”
Created
   │
   ▼
Validated
   │
   ▼
Scheduled
   │
   ▼
Running
   │
   ├────────► Waiting
   │             │
   │             ▼
   │          Resumed
   ▼
Completed
   │
   ├────────► Failed
   ├────────► Cancelled
   └────────► Compensated

Every state transition is persisted.

8. Activity Categories

Section titled “8. Activity Categories”

The engine supports multiple activity types:

Activity TypePurpose
FunctionExecute Rust code
HTTPInvoke REST APIs
gRPCCall remote services
AIInvoke LLM providers
ToolExecute registered tools
ScriptRun sandboxed scripts
TimerDelay execution
HumanAwait manual approval
EventWait for external event
Sub-workflowInvoke another workflow

Each activity type shares a common execution contract.

9. Execution Model

Section titled “9. Execution Model”

Execution is driven by a state machine.

Key characteristics:

  • Durable checkpoints
  • Explicit state transitions
  • Replay support
  • Optimistic concurrency
  • Deterministic scheduling

No workflow progress is lost after a process restart.

10. Persistence

Section titled “10. Persistence”

Workflow state is persisted after every significant transition.

Persisted data includes:

  • Current state
  • Activity status
  • Variables
  • Event history
  • Retry counters
  • Checkpoints

Persistence is abstracted behind repository interfaces.

11. Scheduling

Section titled “11. Scheduling”

Scheduling capabilities include:

  • Immediate execution
  • Delayed execution
  • Cron schedules
  • Periodic execution
  • Event-triggered execution

Scheduling is delegated to the Scheduler component.

12. Failure Handling

Section titled “12. Failure Handling”

The engine supports:

  • Configurable retry policies
  • Exponential backoff
  • Compensation workflows
  • Dead-letter handling
  • Manual intervention

Failure handling policies are defined per activity and workflow.

13. Observability

Section titled “13. Observability”

Every workflow execution emits:

  • Lifecycle events
  • Metrics
  • Structured logs
  • Distributed traces

Operators should be able to inspect:

  • Current state
  • Activity history
  • Retry attempts
  • Timing information

14. Security

Section titled “14. Security”

Workflow execution must enforce:

  • Authorization
  • Tenant isolation
  • Activity permissions
  • Secret masking
  • Audit logging

Sensitive workflow data should be protected at rest and in transit.

15. Scalability

Section titled “15. Scalability”

The engine supports:

  • Horizontal worker scaling
  • Distributed execution
  • Queue-based scheduling
  • Partitioned workloads

Execution ownership can move between workers without losing progress.

16. Extensibility

Section titled “16. Extensibility”

The Workflow Engine supports extension through:

  • Custom activity types
  • Scheduling strategies
  • Persistence providers
  • Event bus implementations
  • Serialization formats
  • Monitoring integrations

Extensions must implement stable public interfaces.

17. Integration Points

Section titled “17. Integration Points”

Primary integrations include:

  • Agent Runtime
  • Memory Engine
  • LLM Gateway
  • Tool Runtime
  • Event Bus
  • Scheduler
  • Platform Kernel

Each integration is accessed through ports defined by the domain layer.

18. Non-Functional Requirements

Section titled “18. Non-Functional Requirements”
RequirementTarget
Workflow startup latency< 100 ms
Activity scheduling latency< 50 ms
Workflow durabilityNo data loss after checkpoint
Horizontal scalabilityLinear scaling with workers
Availability99.9%+
Replay capabilityFull execution history
Section titled “19. Related Documents”
  • Execution Model
  • Workflow DSL
  • DAG Engine
  • Scheduler
  • State Machine
  • Checkpointing
  • Retry Engine
  • Compensation
  • Distributed Execution
  • Persistence
  • Rust Crate Design
  • Temporal Gap Closure (next phase)

20. Revision History

Section titled “20. Revision History”
VersionDateDescription
1.0.02026-06-26Initial Workflow Engine Overview