Execution Engine
The Execution Engine is a durable state machine that runs validated plans step-by-step. It checkpoints after every state transition, survives process restarts, handles governance gates and user interactions, and defers external side effects until all steps succeed.
import { ExecutionEngine, CapabilityImplementationRegistry, CheckpointManager } from '@zakardo/core';import type { ExecutionRequest, ExecutionResult } from '@zakardo/core';
const engine = new ExecutionEngine({ implementationRegistry, checkpointManager, policyEngine, traceWriter, store, config: { timeout_ms: 60_000, step_timeout_ms: 10_000 },});
// Start an executionconst result: ExecutionResult = await engine.start({ plan: validatedPlanIR, mode: 'LIVE', user_context: { user_id: 'user-1', roles: ['admin'] }, intent: { expressed: 'List all contacts' },});
console.log(result.status); // 'COMPLETED' | 'FAILED' | 'GATE_PENDING' | ...console.log(result.execution_id);Execution States
Section titled “Execution States”stateDiagram-v2 [*] --> PENDING PENDING --> RUNNING RUNNING --> STEP_EXECUTING STEP_EXECUTING --> RUNNING: step completed STEP_EXECUTING --> GATE_PENDING: gate triggered STEP_EXECUTING --> INTERACTION_PENDING: interaction needed STEP_EXECUTING --> RETRYING: transient error GATE_PENDING --> RUNNING: approved GATE_PENDING --> FAILED: rejected/timeout INTERACTION_PENDING --> RUNNING: user responded INTERACTION_PENDING --> FAILED: timeout RETRYING --> STEP_EXECUTING: retry attempt RETRYING --> FAILED: budget exhausted RUNNING --> COMPLETED: all steps done RUNNING --> FAILED: permanent errorTerminal states: COMPLETED, FAILED, CANCELLED
Key Components
Section titled “Key Components”ExecutionContext
Section titled “ExecutionContext”Runtime accumulator that holds all data flowing through the plan:
import { ExecutionContext, resolveBinding, resolveStepInputs } from '@zakardo/core';
// The context accumulates step outputs as the plan executes// Access via path expressions:// $context.plan.inputs.tag → plan-level input// $context.steps.step_0.output.contacts → step 0's output// $context.system.timestamp → execution timestampCheckpointManager
Section titled “CheckpointManager”Persists execution state after every transition. If the process crashes, execution resumes from the last checkpoint:
import { CheckpointManager } from '@zakardo/core';
const manager = new CheckpointManager(store);// Automatically used by the ExecutionEngine — no direct setup neededCapabilityImplementationRegistry
Section titled “CapabilityImplementationRegistry”Maps capability names to their implementation functions:
import { CapabilityImplementationRegistry } from '@zakardo/core';
const registry = new CapabilityImplementationRegistry();registry.register('contacts_list', '1.0.0', listContactsImpl);registry.register('contacts_create', '1.0.0', createContactImpl);Execution Modes
Section titled “Execution Modes”| Mode | READ capabilities | WRITE capabilities | External effects |
|---|---|---|---|
SIMULATED | Simulated | Simulated | None |
DRY_RUN | Execute | Logged, not committed | None |
LIVE | Execute | Execute | Committed on success |
TRAINING | Execute | Execute | Committed (with detailed traces) |
Gate Handling
Section titled “Gate Handling”When a governance policy triggers a GATE action during execution:
import { GateHandler } from '@zakardo/core';
// The engine pauses and emits a gate event// Approve/reject via the REST API:// POST /zakardo/v1/executions/:id/gate// { "gate_id": "...", "approved": true }Gates have configurable timeouts. Default: 5 minutes.
Interaction Handling
Section titled “Interaction Handling”When a capability has an interaction_spec, execution pauses for user input:
import { InteractionHandler } from '@zakardo/core';
// The engine pauses and emits an interaction event// Respond via the REST API:// POST /zakardo/v1/executions/:id/interaction// { "interaction_id": "...", "response": { "selected": "option-a" } }Retry Handling
Section titled “Retry Handling”Transient errors (network timeouts, rate limits) trigger automatic retry with exponential backoff:
import { RetryHandler, DEFAULT_RETRY_CONFIG } from '@zakardo/core';
// Default config:// max_attempts: 3// initial_delay_ms: 1000// max_delay_ms: 30000// backoff_multiplier: 2Permanent errors (validation failures, business logic errors) are not retried.
The Outbox Pattern
Section titled “The Outbox Pattern”External side effects (WRITE_EXTERNAL) are managed through the Outbox:
import { OutboxManager } from '@zakardo/core';
// During execution:// 1. External effects are STAGED (not sent)// 2. If all steps succeed → effects are COMMITTED (sent)// 3. If any step fails → effects are DISCARDED (never sent)This prevents partial execution from producing orphaned side effects.
Execution Result
Section titled “Execution Result”interface ExecutionResult { execution_id: ExecutionId; status: ExecutionStatus; plan_id: PlanId; started_at: string; completed_at?: string; duration_ms?: number; step_results: StepResult[]; error?: ExecutionError;}Further Reading
Section titled “Further Reading”- Architecture Overview — how the engine fits into the system
- Traces — what the engine records during execution
- Execution Engine Specification — full 1,600-line specification