Skip to content

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 execution
const 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);
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 error

Terminal states: COMPLETED, FAILED, CANCELLED

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 timestamp

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 needed

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);
ModeREAD capabilitiesWRITE capabilitiesExternal effects
SIMULATEDSimulatedSimulatedNone
DRY_RUNExecuteLogged, not committedNone
LIVEExecuteExecuteCommitted on success
TRAININGExecuteExecuteCommitted (with detailed traces)

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.

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" } }

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: 2

Permanent errors (validation failures, business logic errors) are not retried.

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.

interface ExecutionResult {
execution_id: ExecutionId;
status: ExecutionStatus;
plan_id: PlanId;
started_at: string;
completed_at?: string;
duration_ms?: number;
step_results: StepResult[];
error?: ExecutionError;
}