@orbytautomation/engine 0.3.0 → 0.4.1

package/dist/types/core-types.d.ts

@@ -1,4 +1,16 @@
-import { OwnershipContext } from "../execution/InternalExecutionContext.js";
+import { Adapter, AdapterResult, ExitCodes, TriggerType as TriggerEnums } from "@dev-ecosystem/core";
+import { TimeoutError, TimeoutManager } from "../automation/TimeoutManager.js";
+import { BackoffStrategy } from "../automation/BackoffStrategy.js";
+import { RetryPolicy } from "../automation/RetryPolicy.js";
+import { EngineLogger } from "../logging/EngineLogger.js";
+import { LifecycleHook } from "../hooks/LifecycleHooks.js";
+import { WorkflowExecutor } from "../execution/WorkflowExecutor.js";
+import { StepExecutor } from "../execution/StepExecutor.js";
+import { AdapterRegistry } from "../adapters/AdapterRegistry.js";
+import { HookManager } from "../hooks/HookManager.js";
+import { ExecutionEngine } from "../execution/ExecutionEngine.js";
+import { EventBus } from "../events/EventBus.js";
+import { ErrorSeverity, OrbytErrorCode } from "../errors/ErrorCodes.js";
 /**
  * Workflow run options
  * User-friendly options for running a workflow
@@ -41,19 +53,2309 @@ export interface WorkflowRunOptions {
      * INTERNAL USE: Not for user workflows
      */
     _ownershipContext?: Partial<OwnershipContext>;
+    /**
+     * Permission policy for this execution
+     */
+    _permissionPolicy?: PermissionPolicy;
 }
 /**
- * Workflow load options
- * Options for loading a workflow from file
+ * Workflow loading options
  */
 export interface WorkflowLoadOptions {
     /**
      * Base directory for resolving relative paths
+     * Defaults to dirname of the loaded file
      */
     baseDir?: string;
     /**
-     * Variables to inject during parsing
+     * Variables to inject during loading
      */
     variables?: Record<string, any>;
+    /**
+     * Whether to validate the workflow after loading
+     * Default: true
+     */
+    validate?: boolean;
+    /**
+     * Optional EngineLogger for structured error logging
+     */
+    logger?: EngineLogger;
+}
+/**
+ * Execution Identity (Engine-Generated)
+ * Generated for each workflow execution
+ */
+export interface ExecutionIdentity {
+    /** Unique execution ID (generated by engine) */
+    executionId: string;
+    /** Run ID for this workflow execution */
+    runId: string;
+    /** Trace ID for distributed tracing */
+    traceId: string;
+    /** Parent run ID if this is a nested workflow */
+    parentRunId?: string;
+    /** Execution start timestamp */
+    startedAt: Date;
+    /** Engine version that executed this workflow */
+    engineVersion: string;
+    /** Node ID for future distributed execution */
+    nodeId?: string;
+}
+/**
+ * Ownership Context (From Bridge/API)
+ * Passed from website/bridge to engine
+ */
+export interface OwnershipContext {
+    /** User ID who triggered execution */
+    userId: string;
+    /** Workspace/organization ID */
+    workspaceId: string;
+    /** Subscription ID */
+    subscriptionId: string;
+    /** Subscription tier (free, pro, enterprise) */
+    subscriptionTier: string;
+    /** Geographic region */
+    region: string;
+    /** Pricing model (ecosystem | component) */
+    pricingModel: 'ecosystem' | 'component';
+    /** Billing mode  */
+    billingMode: 'ecosystem' | 'component';
+}
+/**
+ * Billing Snapshot (Frozen at Execution Start)
+ * Prevents billing disputes when pricing changes
+ */
+export interface BillingSnapshot {
+    /** Base cost per automation execution */
+    baseExecutionCost: number;
+    /** Base cost per step */
+    baseStepCost: number;
+    /** Pricing tier at execution time */
+    pricingTier: string;
+    /** Discount applied (%) */
+    discountApplied: number;
+    /** Promo code applied */
+    promoApplied?: string;
+    /** Effective rate after discounts */
+    effectiveRate: number;
+    /** Billing snapshot version (for audit) */
+    snapshotVersion: string;
+    /** Timestamp when snapshot was taken */
+    snapshotAt: Date;
+}
+/**
+ * Usage Counters (Engine-Calculated)
+ * Never user-editable
+ */
+export interface UsageCounters {
+    /** Number of automations executed (always 1 per workflow) */
+    automationCount: number;
+    /** Total number of steps executed */
+    stepCount: number;
+    /** Weighted step count (sum of step weights) */
+    weightedStepCount: number;
+    /** Execution duration in seconds */
+    durationSeconds: number;
+    /** CPU usage (future) */
+    resourceUsageCpu?: number;
+    /** Memory usage (future) */
+    resourceUsageMemory?: number;
+}
+/**
+ * Derived Billing Context (Engine-Computed)
+ * Calculated based on ownership + snapshot
+ */
+export interface DerivedBillingContext {
+    /** Is this execution billable */
+    isBillable: boolean;
+    /** Billing scope resolved */
+    billingScopeResolved: 'workflow' | 'step' | 'both';
+    /** Effective product billing to */
+    effectiveProduct: string;
+    /** Pricing tier resolved from subscription */
+    pricingTierResolved: string;
+    /** Final cost calculated */
+    totalCost: number;
+}
+/**
+ * Security Metadata (Engine-Controlled)
+ * Security boundaries and permissions
+ */
+export interface SecurityMetadata {
+    /** Payment status (affects execution) */
+    paymentStatus: 'active' | 'past_due' | 'canceled' | 'trial';
+    /** Request source IP (optional) */
+    ipAddress?: string;
+    /** Security policy version */
+    securityPolicyVersion?: string;
+    /** Execution isolation level */
+    isolationLevel: 'process' | 'container' | 'vm';
+    /** Permissions granted for this execution */
+    permissionsGranted: string[];
+}
+/**
+ * Runtime State (Engine-Managed)
+ * Current execution state
+ */
+export interface RuntimeState {
+    /** Current workflow state */
+    workflowState: 'pending' | 'running' | 'completed' | 'failed' | 'timeout' | 'cancelled';
+    /** Actual retry count (not user-defined max) */
+    retryCountActual: number;
+    /** Was timeout triggered? */
+    timeoutTriggered: boolean;
+    /** Execution graph (resolved dependencies) */
+    executionGraph?: Record<string, string[]>;
+    /** Steps state map */
+    stepsState: Record<string, 'pending' | 'running' | 'completed' | 'failed' | 'skipped'>;
+}
+/**
+ * Request Context (Origin Information)
+ * Where the execution request came from
+ */
+export interface RequestContext {
+    /** Request origin */
+    origin: 'cli' | 'api' | 'sdk' | 'webhook' | 'scheduler';
+    /** Execution mode */
+    mode: 'local' | 'server' | 'embedded' | 'dry-run';
+    /** Who/what triggered this */
+    triggeredBy?: string;
+}
+/**
+ * Internal Execution Context (Complete)
+ * This is what engine maintains internally. NEVER exposed to workflow.
+ */
+export interface InternalExecutionContext {
+    /** Execution identity */
+    _identity: ExecutionIdentity;
+    /** Ownership from bridge */
+    _ownership: OwnershipContext;
+    /** Billing snapshot (frozen) */
+    _billingSnapshot: BillingSnapshot;
+    /** Usage counters */
+    _usage: UsageCounters;
+    /** Derived billing context */
+    _billing: DerivedBillingContext;
+    /** Tier-based execution limits (ENFORCED by engine) */
+    _limits: TierLimits;
+    /** Security metadata */
+    _security: SecurityMetadata;
+    /** Runtime state */
+    _runtime: RuntimeState;
+    /** Request context */
+    _request: RequestContext;
+    /** Audit metadata */
+    _audit: {
+        engineVersion: string;
+        billingSnapshotVersion: string;
+        executionVersion: string;
+    };
+}
+/**
+ * Step-level Internal Context
+ * Injected into each step execution
+ */
+export interface InternalStepContext {
+    /** Step usage (engine-calculated from user weight or default) */
+    usage: {
+        billable: boolean;
+        unit: string;
+        weight: number;
+        computedCost: number;
+    };
+    /** Step requirements (engine-validated) */
+    requires: {
+        capabilities: string[];
+        validated: boolean;
+    };
+    /** Execution hints (engine-optimized) */
+    hints: {
+        cacheable: boolean;
+        idempotent: boolean;
+        heavy: boolean;
+        cost: 'free' | 'low' | 'medium' | 'high';
+    };
+}
+/**
+ * Execution limits based on subscription tier
+ */
+export interface TierLimits {
+    /** Maximum retry attempts per step */
+    maxRetryAttempts: number;
+    /** Maximum step timeout in milliseconds */
+    maxStepTimeout: number;
+    /** Maximum workflow timeout in milliseconds */
+    maxWorkflowTimeout: number;
+    /** Maximum concurrent steps */
+    maxConcurrency: number;
+    /** Maximum steps per workflow */
+    maxStepsPerWorkflow: number;
+    /** Maximum workflow depth (nested workflows) */
+    maxWorkflowDepth: number;
+    /** Maximum file size for FS operations (bytes) */
+    maxFileSize: number;
+    /** Maximum HTTP request timeout (ms) */
+    maxHttpTimeout: number;
+    /** Allowed execution modes */
+    allowedExecutionModes: Array<'local' | 'docker' | 'remote' | 'distributed'>;
+    /** Minimum sandbox level */
+    minSandboxLevel: 'none' | 'basic' | 'strict';
+    /** Can disable sandboxing */
+    canDisableSandbox: boolean;
+    /** Can set high priority */
+    canSetHighPriority: boolean;
+    /** Maximum CPU cores */
+    maxCpu: number;
+    /** Maximum memory (MB) */
+    maxMemoryMB: number;
+    /** Maximum disk space (MB) */
+    maxDiskMB: number;
+}
+/**
+ * Default limits for free tier (most restrictive)
+ */
+export declare const FREE_TIER_LIMITS: TierLimits;
+/**
+ * Pro tier limits
+ */
+export declare const PRO_TIER_LIMITS: TierLimits;
+/**
+ * Enterprise tier limits
+ */
+export declare const ENTERPRISE_TIER_LIMITS: TierLimits;
+/**
+ * Execution trigger type
+ */
+export type TriggerType = TriggerEnums.Cron | TriggerEnums.Interval | TriggerEnums.Once | TriggerEnums.Manual | TriggerEnums.Event | TriggerEnums.Webhook;
+/**
+ * Workflow execution job payload
+ */
+export interface WorkflowExecutionPayload {
+    /** Workflow definition (YAML string or parsed object) */
+    workflow: string | ParsedWorkflow;
+    /** Execution options */
+    options?: ExecutionOptions;
+    /** Trigger information */
+    trigger: {
+        type: TriggerType;
+        source?: string;
+        metadata?: Record<string, any>;
+    };
+}
+/**
+ * Execution engine configuration
+ */
+export interface EngineConfig {
+    /** Maximum concurrent workflow executions */
+    maxConcurrentExecutions?: number;
+    /** Default workflow timeout (ms) */
+    defaultTimeout?: number;
+    /** Enable scheduler */
+    enableScheduler?: boolean;
+    /** Custom job queue (default: InMemoryQueue) */
+    queue?: JobQueue;
+    /** Global retry policy for workflows */
+    retryPolicy?: RetryPolicy;
+    /** Timeout manager instance */
+    timeoutManager?: TimeoutManager;
+}
+/**
+ * Workflow execution status
+ */
+export interface WorkflowExecutionStatus {
+    /** Execution ID */
+    executionId: string;
+    /** Workflow name */
+    workflowName: string;
+    /** Current status */
+    status: 'queued' | 'running' | 'completed' | 'failed' | 'timeout';
+    /** Trigger information */
+    trigger: {
+        type: TriggerType;
+        source?: string;
+        triggeredAt: Date;
+    };
+    /** Execution result (if completed) */
+    result?: WorkflowResult;
+    /** Error (if failed) */
+    error?: Error;
+    /** Progress information */
+    progress?: {
+        currentStep?: string;
+        completedSteps: number;
+        totalSteps: number;
+    };
+}
+/**
+ * Retry condition - determines if error is retryable
+ */
+export type RetryCondition = (error: Error, attempt: number) => boolean;
+/**
+ * Retry policy configuration
+ */
+export interface RetryPolicyConfig {
+    /** Maximum retry attempts (0 = no retries) */
+    maxAttempts: number;
+    /** Backoff strategy for delays between retries */
+    backoffStrategy: BackoffStrategy;
+    /** Custom retry condition (default: retry all errors) */
+    retryCondition?: RetryCondition;
+    /** Specific error types to retry (if provided, only these are retried) */
+    retryableErrors?: Array<new (...args: any[]) => Error>;
+    /** Error messages to match for retry (regex patterns) */
+    retryableMessages?: RegExp[];
+    /** Abort retry on specific errors (overrides other conditions) */
+    abortOn?: Array<new (...args: any[]) => Error>;
+}
+/**
+ * Backoff strategy type
+ */
+export type BackoffType = 'fixed' | 'linear' | 'exponential';
+/**
+ * Backoff strategy configuration
+ */
+export interface BackoffConfig {
+    /** Strategy type */
+    type: BackoffType;
+    /** Base delay in milliseconds */
+    baseDelayMs: number;
+    /** Maximum delay cap in milliseconds */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    multiplier?: number;
+    /** Add random jitter (0-1, default: 0.1 = 10%) */
+    jitter?: number;
+}
+/**
+ * Timeout configuration
+ */
+export interface TimeoutConfig {
+    /** Timeout duration in milliseconds */
+    timeoutMs: number;
+    /** Operation name for error messages */
+    operation?: string;
+    /** Cleanup function to run on timeout */
+    onTimeout?: () => Promise<void> | void;
+    /** Whether to run cleanup before throwing (default: true) */
+    cleanupBeforeThrow?: boolean;
+}
+/**
+ * Timeout result
+ */
+export interface TimeoutResult<T> {
+    /** Operation result (undefined if timed out) */
+    result?: T;
+    /** Whether operation timed out */
+    timedOut: boolean;
+    /** Actual duration in milliseconds */
+    durationMs: number;
+    /** Timeout error if timed out */
+    error?: TimeoutError;
+}
+/**
+ * Job status
+ */
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'retrying';
+/**
+ * Job priority levels
+ */
+export declare enum JobPriority {
+    LOW = 0,
+    NORMAL = 1,
+    HIGH = 2,
+    CRITICAL = 3
+}
+/**
+ * Job metadata
+ */
+export interface JobMetadata {
+    /** When job was created */
+    createdAt: Date;
+    /** When job started executing */
+    startedAt?: Date;
+    /** When job completed */
+    completedAt?: Date;
+    /** Execution duration in ms */
+    durationMs?: number;
+    /** Job tags for filtering/grouping */
+    tags?: string[];
+    /** Custom metadata */
+    [key: string]: any;
+}
+/**
+ * Job for workflow/step execution
+ */
+export interface Job<T = any> {
+    /** Unique job ID */
+    id: string;
+    /** Associated workflow ID */
+    workflowId: string;
+    /** Optional step ID (if job is for single step) */
+    stepId?: string;
+    /** Job type (workflow, step, etc.) */
+    type: 'workflow' | 'step';
+    /** Job payload/input data */
+    payload: T;
+    /** Current status */
+    status: JobStatus;
+    /** Priority level */
+    priority: JobPriority;
+    /** Number of execution attempts */
+    attempts: number;
+    /** Maximum retry attempts allowed */
+    maxRetries: number;
+    /** Backoff delay for retries (ms) */
+    retryDelayMs?: number;
+    /** Errors from previous attempts */
+    errors: Error[];
+    /** Job result (if completed) */
+    result?: any;
+    /** Job metadata */
+    metadata: JobMetadata;
+    /** Timeout for job execution (ms) */
+    timeoutMs?: number;
+    /** Jobs that must complete before this one */
+    dependencies?: string[];
+}
+/**
+ * Queue statistics
+ */
+export interface QueueStats {
+    /** Total jobs in queue */
+    total: number;
+    /** Pending jobs */
+    pending: number;
+    /** Running jobs */
+    running: number;
+    /** Completed jobs */
+    completed: number;
+    /** Failed jobs */
+    failed: number;
+    /** Jobs awaiting retry */
+    retrying: number;
+    /** Average wait time (ms) */
+    avgWaitTimeMs: number;
+    /** Average execution time (ms) */
+    avgExecutionTimeMs: number;
+}
+/**
+ * Queue configuration
+ */
+export interface QueueConfig {
+    /** Maximum queue size (0 = unlimited) */
+    maxSize?: number;
+    /** Maximum concurrent jobs */
+    maxConcurrent?: number;
+    /** Enable job persistence */
+    persistent?: boolean;
+    /** Job retention time (ms) */
+    retentionMs?: number;
+}
+/**
+ * Job queue interface
+ */
+export interface JobQueue<T = any> {
+    /**
+     * Add job to queue
+     *
+     * @param job - Job to enqueue
+     * @returns Promise resolving when job is queued
+     */
+    enqueue(job: Job<T>): Promise<void>;
+    /**
+     * Remove and return highest priority pending job
+     *
+     * @returns Next job or null if queue is empty
+     */
+    dequeue(): Promise<Job<T> | null>;
+    /**
+     * Peek at next job without removing it
+     *
+     * @returns Next job or null if queue is empty
+     */
+    peek(): Promise<Job<T> | null>;
+    /**
+     * Get job by ID
+     *
+     * @param jobId - Job ID
+     * @returns Job or null if not found
+     */
+    getJob(jobId: string): Promise<Job<T> | null>;
+    /**
+     * Mark job as completed successfully
+     *
+     * @param jobId - Job ID
+     * @param result - Job result
+     */
+    markCompleted(jobId: string, result?: any): Promise<void>;
+    /**
+     * Mark job as failed
+     *
+     * @param jobId - Job ID
+     * @param error - Error that caused failure
+     */
+    markFailed(jobId: string, error: Error): Promise<void>;
+    /**
+     * Mark job as retrying
+     *
+     * @param jobId - Job ID
+     */
+    markRetrying(jobId: string): Promise<void>;
+    /**
+     * Remove job from queue
+     *
+     * @param jobId - Job ID
+     * @returns True if job was removed
+     */
+    remove(jobId: string): Promise<boolean>;
+    /**
+     * Get all jobs matching filter
+     *
+     * @param filter - Filter function
+     * @returns Matching jobs
+     */
+    find(filter: (job: Job<T>) => boolean): Promise<Job<T>[]>;
+    /**
+     * Get queue statistics
+     *
+     * @returns Queue stats
+     */
+    getStats(): Promise<QueueStats>;
+    /**
+     * Clear all jobs from queue
+     */
+    clear(): Promise<void>;
+    /**
+     * Get queue size
+     *
+     * @returns Number of jobs in queue
+     */
+    size(): Promise<number>;
+    /**
+     * Check if queue is empty
+     *
+     * @returns True if queue has no jobs
+     */
+    isEmpty(): Promise<boolean>;
+}
+/**
+ * Parsed workflow ready for execution
+ */
+export interface ParsedWorkflow {
+    /** Workflow metadata */
+    name?: string;
+    description?: string;
+    version: string;
+    kind: string;
+    tags?: string[];
+    owner?: string;
+    /** Metadata object (if provided separately) */
+    metadata?: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+        owner?: string;
+        version?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+    /** Annotations for AI and UI hints */
+    annotations?: {
+        'ai.intent'?: string;
+        'ui.group'?: string;
+        'ui.icon'?: string;
+        [key: string]: any;
+    };
+    /** Workflow steps */
+    steps: ParsedStep[];
+    /** Global workflow inputs */
+    inputs?: Record<string, any>;
+    /** Global environment variables */
+    context?: Record<string, any>;
+    /** Secret references */
+    secrets?: {
+        vault?: string;
+        refs?: Record<string, string>;
+    };
+    /** Trigger configuration */
+    triggers?: Array<{
+        type: string;
+        [key: string]: any;
+    }>;
+    /** Defaults */
+    defaults?: {
+        retry?: {
+            max: number;
+            backoff?: 'linear' | 'exponential';
+            delay?: number;
+        };
+        timeout?: string;
+        adapter?: string;
+    };
+    /** Policies */
+    policies?: {
+        failure?: 'stop' | 'continue' | 'isolate';
+        concurrency?: number;
+        sandbox?: 'none' | 'basic' | 'strict';
+    };
+    /** Permissions */
+    permissions?: any;
+    /** Resources */
+    resources?: any;
+    /** Outputs */
+    outputs?: Record<string, string>;
+}
+/**
+ * Parsed internal step representation
+ */
+export interface ParsedStep {
+    /** Unique step identifier */
+    id: string;
+    /** Adapter type (http, shell, cli, plugin, etc.) */
+    adapter: string;
+    /** Full action name (e.g., 'http.request.get') */
+    action: string;
+    /** Input parameters for the step */
+    input: Record<string, any>;
+    /** Step dependencies (other step IDs) */
+    needs: string[];
+    /** Optional name */
+    name?: string;
+    /** Conditional execution expression */
+    when?: string;
+    /** Continue workflow on failure */
+    continueOnError: boolean;
+    /** Retry policy configuration */
+    retry?: {
+        /** Maximum number of retry attempts */
+        max: number;
+        /** Backoff strategy (linear or exponential) */
+        backoff?: 'linear' | 'exponential';
+        /** Delay between retries in milliseconds */
+        delay?: number;
+        /** Store the current retry count */
+        count?: number;
+    };
+    /** Timeout string (e.g., '30s', '5m') */
+    timeout?: string;
+    /** Environment variables for this step */
+    env?: Record<string, string>;
+    /** Output mappings */
+    outputs?: Record<string, string>;
+}
+/**
+ * Workflow execution result
+ */
+export interface WorkflowResult {
+    /** Workflow name */
+    workflowName: string;
+    /** Overall status */
+    status: 'success' | 'failure' | 'partial' | 'timeout';
+    /** All step results */
+    stepResults: Map<string, StepResult>;
+    /** Total execution duration (ms) */
+    duration: number;
+    /** Start timestamp */
+    startedAt: Date;
+    /** End timestamp  */
+    completedAt: Date;
+    /** Error if workflow failed */
+    error?: Error;
+    /** Execution metadata */
+    metadata: {
+        totalSteps: number;
+        successfulSteps: number;
+        failedSteps: number;
+        skippedSteps: number;
+        phases: number;
+    };
+}
+/**
+ * Workflow execution options
+ */
+export interface ExecutionOptions {
+    /** Workflow timeout (ms) */
+    timeout?: number;
+    /** Initial environment variables */
+    env?: Record<string, any>;
+    /** Workflow inputs */
+    inputs?: Record<string, any>;
+    /** Resolved secrets */
+    secrets?: Record<string, any>;
+    /** Additional context */
+    context?: Record<string, any>;
+    /** Continue on step failure */
+    continueOnError?: boolean;
+    /** Trigger source (who/what triggered this execution) */
+    triggeredBy?: string;
+}
+/**
+ * Runtime context for variable resolution
+ */
+export interface ResolutionContext {
+    /** Global environment variables */
+    env: Record<string, any>;
+    /** Step outputs (stepId -> output data) */
+    steps: Map<string, any>;
+    /** Workflow metadata */
+    workflow: {
+        id: string;
+        name: string;
+        version?: string;
+        description?: string;
+        tags?: string[];
+        owner?: string;
+    };
+    /** Current run information */
+    run: {
+        id: string;
+        timestamp: Date;
+        attempt: number;
+        startedAt?: Date;
+        triggeredBy?: string;
+    };
+    /** Workflow inputs (runtime parameters) */
+    inputs?: Record<string, any>;
+    /** Resolved secrets (name -> value) */
+    secrets?: Record<string, any>;
+    /** Additional runtime context */
+    context?: Record<string, any>;
+    /** Workflow metadata (extended) */
+    metadata?: {
+        createdAt?: string;
+        updatedAt?: string;
+        annotations?: Record<string, any>;
+    };
+    /** Telemetry data (future) */
+    telemetry?: Record<string, any>;
+    /** Resource information (future) */
+    resources?: Record<string, any>;
+    /** Compliance metadata (future) */
+    compliance?: Record<string, any>;
+}
+/**
+ * Step execution result
+ */
+export interface StepResult {
+    /** Step ID */
+    stepId: string;
+    /** Execution status */
+    status: 'success' | 'failure' | 'skipped' | 'timeout';
+    /** Step output data */
+    output: any;
+    /** Error if failed */
+    error?: Error;
+    /** Execution duration (ms) */
+    duration: number;
+    /** Number of retry attempts */
+    attempts: number;
+    /** Start timestamp */
+    startedAt: Date;
+    /** End timestamp */
+    completedAt: Date;
+}
+/**
+ * Adapter interface for step execution
+ */
+export interface StepAdapter {
+    /** Adapter name */
+    name: string;
+    /**
+     * Execute step with the adapter
+     *
+     * @param action - Full action name (e.g., 'http.request.get')
+     * @param input - Resolved input parameters
+     * @param context - Execution context
+     * @returns Adapter output
+     */
+    execute(action: string, input: Record<string, any>, context: any): Promise<any>;
+}
+/**
+ * Step execution context for drivers
+ */
+export interface DriverContext {
+    /** Current step ID */
+    stepId: string;
+    /** Workflow execution ID */
+    executionId: string;
+    /** Workflow name */
+    workflowName: string;
+    /** Logger function */
+    log: (message: string, level?: 'info' | 'warn' | 'error' | 'debug') => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Step timeout in milliseconds */
+    timeout?: number;
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Secrets access */
+    secrets?: Record<string, string>;
+    /** Temporary directory */
+    tempDir?: string;
+    /** Previous step outputs */
+    stepOutputs?: Record<string, any>;
+    /** Workflow inputs */
+    inputs?: Record<string, any>;
+    /** Workflow context */
+    workflowContext?: Record<string, any>;
+}
+/**
+ * Step definition for driver execution
+ */
+export interface DriverStep {
+    /** Step ID */
+    id: string;
+    /** Step name (optional) */
+    name?: string;
+    /** Action to execute (e.g., 'http.request.get', 'cli.run') */
+    uses: string;
+    /** Input parameters */
+    with?: Record<string, any>;
+    /** Conditional execution */
+    when?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Retry configuration */
+    retry?: {
+        max: number;
+        backoff?: 'linear' | 'exponential';
+        delay?: number;
+    };
+    /** Timeout */
+    timeout?: string;
+    /** Continue on error */
+    continueOnError?: boolean;
+}
+/**
+ * Base execution driver interface
+ */
+export interface ExecutionDriver {
+    /** Driver type identifier */
+    readonly type: string;
+    /** Driver name */
+    readonly name: string;
+    /** Driver version */
+    readonly version: string;
+    /** Driver description */
+    readonly description?: string;
+    /**
+     * Check if this driver can handle a step
+     *
+     * @param step - Step to check
+     * @returns True if driver can handle this step
+     */
+    canHandle(step: DriverStep): boolean;
+    /**
+     * Execute a step
+     *
+     * @param step - Step to execute
+     * @param context - Execution context
+     * @returns Execution result
+     */
+    execute(step: DriverStep, context: DriverContext): Promise<AdapterResult>;
+    /**
+     * Optional: Initialize driver
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Optional: Cleanup driver
+     */
+    cleanup?(): Promise<void>;
+}
+/**
+ * Execution phase (group of steps that can run in parallel)
+ */
+export interface ExecutionPhase {
+    /** Phase number (0-indexed) */
+    readonly phase: number;
+    /** Nodes that can execute in parallel */
+    readonly nodes: readonly ExecutionNode[];
+    /** Combined phase timeout (max of all node timeouts) */
+    readonly timeout?: number;
+}
+/**
+ * Complete execution plan for a workflow.
+ * This is a blueprint for execution - it contains NO execution state.
+ */
+export interface ExecutionPlan {
+    /** Ordered phases of execution */
+    readonly phases: readonly ExecutionPhase[];
+    /** The validated dependency graph */
+    readonly graph: DependencyGraph;
+    /** Total number of steps */
+    readonly totalSteps: number;
+    /** Maximum parallelism (largest phase size) */
+    readonly maxParallelism: number;
+    /** Critical path length (minimum phases needed) */
+    readonly criticalPathLength: number;
+    /** Topological sort result */
+    readonly sortResult: TopologicalSortResult;
+}
+/**
+ * Represents a directed edge in the dependency graph
+ */
+export interface DependencyEdge {
+    /** The step that depends on another */
+    readonly from: string;
+    /** The step that must complete first */
+    readonly to: string;
+}
+/**
+ * The complete dependency graph structure
+ */
+export interface DependencyGraph {
+    /** All execution nodes indexed by stepId */
+    readonly nodes: ReadonlyMap<string, ExecutionNode>;
+    /** All dependency edges */
+    readonly edges: readonly DependencyEdge[];
+    /** Adjacency list: stepId → list of dependencies */
+    readonly adjacencyList: ReadonlyMap<string, readonly string[]>;
+    /** Reverse adjacency list: stepId → list of dependents */
+    readonly reverseDependencies: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * Result of cycle detection
+ */
+export interface CycleDetectionResult {
+    /** Whether a cycle was detected */
+    readonly hasCycle: boolean;
+    /** The cycle path if one was found (e.g., ['A', 'B', 'C', 'A']) */
+    readonly cyclePath?: readonly string[];
+}
+/**
+ * Node visit state for DFS traversal
+ */
+export declare enum VisitState {
+    /** Not yet visited */
+    WHITE = "white",
+    /** Currently being visited (in DFS stack) */
+    GRAY = "gray",
+    /** Fully visited, all descendants explored */
+    BLACK = "black"
+}
+/**
+ * Result of topological sorting
+ */
+export interface TopologicalSortResult {
+    /**
+     * Execution phases - each inner array is a phase,
+     * steps in the same phase can run in parallel
+     */
+    readonly phases: readonly (readonly string[])[];
+    /**
+     * Total number of phases
+     */
+    readonly phaseCount: number;
+    /**
+     * Map of stepId → phase number (0-indexed)
+     */
+    readonly stepPhases: ReadonlyMap<string, number>;
+}
+/**
+ * Execution state for a single step
+ */
+export type ExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+/**
+ * Pure data model for an execution node in the DAG.
+ * Contains only data - no behavior, no methods (except maybe toString for debugging).
+ */
+export interface ExecutionNode {
+    /**
+     * Unique identifier for this step (from workflow schema)
+     */
+    readonly stepId: string;
+    /**
+     * Step IDs this step depends on (from `needs` field)
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * The resolved adapter instance that will execute this step
+     * This is set during execution planning when adapters are resolved
+     */
+    readonly adapter: Adapter | null;
+    /**
+     * Uses clause - adapter reference from workflow schema (e.g., "fs.read")
+     */
+    readonly uses: string;
+    /**
+     * Input parameters for the adapter
+     */
+    readonly input: Record<string, unknown>;
+    /**
+     * Optional conditional expression
+     * If present and evaluates to false, this step is skipped
+     */
+    readonly condition?: string;
+    /**
+     * Execution metadata
+     */
+    readonly metadata: ExecutionNodeMetadata;
+}
+/**
+ * Metadata about how a step should be executed.
+ * This is data ABOUT execution, not execution itself.
+ */
+export interface ExecutionNodeMetadata {
+    /**
+     * Maximum number of retry attempts (default: 0)
+     */
+    readonly maxRetries: number;
+    /**
+     * Timeout in milliseconds
+     * If not specified, inherits from workflow-level timeout
+     */
+    readonly timeout?: number;
+    /**
+     * Whether this step runs conditionally
+     */
+    readonly hasCondition: boolean;
+    /**
+     * Phase number (from topological sort)
+     * Steps in the same phase can run in parallel
+     */
+    phase?: number;
+}
+/**
+ * Result of critical path analysis
+ */
+export interface CriticalPathResult {
+    /** Steps on the critical path (zero slack) */
+    readonly criticalPath: readonly string[];
+    /** Estimated total workflow duration */
+    readonly workflowDuration: number;
+    /** Earliest start time for each step */
+    readonly earliestStart: ReadonlyMap<string, number>;
+    /** Latest start time for each step without delaying workflow */
+    readonly latestStart: ReadonlyMap<string, number>;
+    /** Slack (float) for each step - how much it can be delayed */
+    readonly slack: ReadonlyMap<string, number>;
+}
+/**
+ * Execution context configuration
+ */
+export interface ContextConfig {
+    /** Execution ID */
+    executionId: string;
+    /** Workflow ID */
+    workflowId: string;
+    /** Workflow name */
+    workflowName: string;
+    /** Workflow version */
+    version?: string;
+    /** Workflow description */
+    description?: string;
+    /** Workflow tags */
+    tags?: string[];
+    /** Workflow owner */
+    owner?: string;
+    /** Runtime inputs */
+    inputs?: Record<string, any>;
+    /** Resolved secrets */
+    secrets?: Record<string, any>;
+    /** Environment variables */
+    env?: Record<string, any>;
+    /** Workflow metadata */
+    metadata?: {
+        createdAt?: string;
+        updatedAt?: string;
+        annotations?: Record<string, any>;
+    };
+    /** Additional context */
+    context?: Record<string, any>;
+    /** Triggered by (user, system, schedule) */
+    triggeredBy?: string;
+}
+/**
+ * Engine runtime context
+ *
+ * Provides access to engine internals during execution.
+ * This is the "global" context available to all components.
+ *
+ * Different from WorkflowHookContext or StepHookContext which are
+ * specific to individual workflow/step executions.
+ *
+ * @example
+ * ```ts
+ * // Inside a custom adapter
+ * async execute(step, context, engineContext) {
+ *   // Access engine components
+ *   engineContext.eventBus.emit(event);
+ *   const otherAdapter = engineContext.adapterRegistry.get('http');
+ * }
+ * ```
+ */
+export interface EngineContext {
+    /**
+     * Engine configuration
+     */
+    config: OrbytEngineConfig;
+    /**
+     * Event bus for emitting and listening to engine events
+     */
+    eventBus: EventBus;
+    /**
+     * Hook manager for lifecycle hooks
+     */
+    hookManager: HookManager;
+    /**
+     * Adapter registry - all registered adapters
+     */
+    adapterRegistry: AdapterRegistry;
+    /**
+     * Execution engine instance
+     */
+    executionEngine: ExecutionEngine;
+    /**
+     * Step executor instance
+     */
+    stepExecutor: StepExecutor;
+    /**
+     * Workflow executor instance
+     */
+    workflowExecutor: WorkflowExecutor;
+    /**
+     * Working directory for this engine instance
+     */
+    workingDirectory: string;
+    /**
+     * Engine start time
+     */
+    startedAt: Date;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Logging level for engine output
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Execution mode
+ */
+export type ExecutionMode = 'local' | 'distributed' | 'dry-run';
+/**
+ * Engine configuration options
+ *
+ * Provides a clean, user-friendly API for configuring OrbytEngine.
+ * All options are optional with sensible defaults.
+ *
+ * @example
+ * ```ts
+ * const config: OrbytEngineConfig = {
+ *   maxConcurrentWorkflows: 5,
+ *   logLevel: 'info',
+ *   enableScheduler: true,
+ *   adapters: [httpAdapter, shellAdapter],
+ *   hooks: [loggingHook, metricsHook]
+ * };
+ *
+ * const engine = new OrbytEngine(config);
+ * ```
+ */
+export interface OrbytEngineConfig {
+    /**
+     * Maximum number of workflows that can run concurrently
+     * @default 10
+     */
+    maxConcurrentWorkflows?: number;
+    /**
+     * Maximum number of steps that can execute concurrently within a workflow
+     * @default 10
+     */
+    maxConcurrentSteps?: number;
+    /**
+     * Default timeout for workflows (milliseconds)
+     * @default 300000 (5 minutes)
+     */
+    defaultTimeout?: number;
+    /**
+     * Execution mode
+     * - 'local': Execute locally with full features
+     * - 'distributed': Execute in distributed mode (future)
+     * - 'dry-run': Validate and plan but don't execute
+     * @default 'local'
+     */
+    mode?: ExecutionMode;
+    /**
+     * Enable the internal scheduler for cron/scheduled workflows
+     * @default true
+     */
+    enableScheduler?: boolean;
+    /**
+     * Custom job queue implementation
+     * If not provided, uses InMemoryQueue
+     */
+    queue?: JobQueue;
+    /**
+     * Global retry policy for all steps
+     * Can be overridden per-step in workflow definition
+     */
+    retryPolicy?: RetryPolicy;
+    /**
+     * Global timeout manager
+     */
+    timeoutManager?: TimeoutManager;
+    /**
+     * Adapters to register with the engine
+     * These will be available for use in workflows
+     */
+    adapters?: Adapter[];
+    /**
+     * Lifecycle hooks for extending engine behavior
+     * Hooks are called at key execution moments
+     */
+    hooks?: LifecycleHook[];
+    /**
+     * Logging level
+     * @default 'info'
+     */
+    logLevel?: LogLevel;
+    /**
+     * Enable verbose output (equivalent to logLevel='debug')
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Enable metrics collection
+     * @default true
+     */
+    enableMetrics?: boolean;
+    /**
+     * Enable event emission
+     * @default true
+     */
+    enableEvents?: boolean;
+    /**
+     * Directory for storing execution state and logs
+     * @default '.orbyt/state'
+     */
+    stateDir?: string;
+    /**
+     * Directory for storing execution logs
+     * @default '.orbyt/logs'
+     */
+    logDir?: string;
+    /**
+     * Sandbox mode for step execution
+     * - 'none': No sandboxing
+     * - 'basic': Basic restrictions
+     * - 'strict': Strict isolation (future)
+     * @default 'basic'
+     */
+    sandboxMode?: 'none' | 'basic' | 'strict';
+    /**
+     * Working directory for workflow execution
+     * @default process.cwd()
+     */
+    workingDirectory?: string;
+    /**
+     * Enable experimental features
+     * @default false
+     */
+    experimental?: boolean;
+    /**
+     * Custom metadata to attach to all executions
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Explanation Types
+ *
+ * Type definitions for workflow execution explanations.
+ * These structures represent a complete analysis of what the engine will do.
+ *
+ * @module explanation
+ */
+/**
+ * Explained step - A single step in the execution plan with all resolved configuration
+ */
+export interface ExplainedStep {
+    /** Step ID */
+    id: string;
+    /** Step name (human-readable) */
+    name?: string;
+    /** Adapter being used (e.g., "shell", "http", "mediaproc") */
+    adapter: string;
+    /** Action to execute (e.g., "shell.exec", "http.request") */
+    uses: string;
+    /** Dependencies - which steps must complete before this one */
+    needs: string[];
+    /** Execution condition (if any) */
+    when?: string;
+    /** Timeout configuration */
+    timeout?: string | number;
+    /** Retry configuration */
+    retry?: {
+        max?: number;
+        backoff?: 'linear' | 'exponential';
+        delay?: number;
+        count?: number;
+    };
+    /** Whether to continue workflow if this step fails */
+    continueOnError?: boolean;
+    /** Input parameters */
+    with?: Record<string, any>;
+    /** Environment variables */
+    env?: Record<string, any>;
+    /** Expected outputs */
+    outputs?: Record<string, any>;
+    /** Secrets used by this step */
+    secretsUsed?: string[];
+    /** Workflow inputs referenced in this step */
+    inputsReferenced?: string[];
+}
+/**
+ * Execution explanation - Complete plan of what the engine will do
+ */
+export interface ExecutionExplanation {
+    /** Workflow name */
+    workflowName?: string;
+    /** Workflow description */
+    description?: string;
+    /** Workflow version */
+    version: string;
+    /** Workflow kind */
+    kind: string;
+    /** Total number of steps */
+    stepCount: number;
+    /** Execution strategy (sequential or parallel) */
+    executionStrategy: 'sequential' | 'parallel' | 'mixed';
+    /** All steps in execution order */
+    steps: ExplainedStep[];
+    /** Whether the workflow has circular dependencies */
+    hasCycles: boolean;
+    /** Cycle details (if any) */
+    cycles?: string[][];
+    /** Total estimated phases (for parallel execution) */
+    phases?: number;
+    /** Dependency graph in adjacency list format */
+    dependencyGraph?: Record<string, string[]>;
+    /** Workflow inputs (parameters the workflow accepts) */
+    inputs?: Record<string, any>;
+    /** Secrets being used (keys only, no values) */
+    secrets?: {
+        vault?: string;
+        keys?: string[];
+    };
+    /** Context variables (environment) */
+    context?: Record<string, any>;
+    /** Workflow outputs */
+    outputs?: Record<string, string>;
+    /** Default configurations */
+    defaults?: {
+        timeout?: string;
+        adapter?: string;
+    };
+    /** Execution policies */
+    policies?: {
+        failure?: 'stop' | 'continue' | 'isolate';
+        concurrency?: number;
+        sandbox?: 'none' | 'basic' | 'strict';
+    };
+    /** Unique adapters used in this workflow */
+    adaptersUsed: string[];
+    /** Adapter actions breakdown (e.g., { "shell": ["exec"], "http": ["request"] }) */
+    adapterActions?: Record<string, string[]>;
+    /** Required workflow inputs */
+    requiredInputs?: string[];
+    /** Optional workflow inputs with defaults */
+    optionalInputs?: Record<string, any>;
+    /** Annotations (AI/UI hints) */
+    annotations?: Record<string, any>;
+    /** Tags */
+    tags?: string[];
+    /** Owner */
+    owner?: string;
+    /** Metadata about workflow complexity */
+    complexity?: {
+        totalSteps: number;
+        maxDepth: number;
+        parallelizableSteps: number;
+        sequentialSteps: number;
+    };
+    /** Data flow prediction - how data moves through the workflow */
+    dataFlow?: DataFlowPrediction[];
+    /** Conditional path analysis - all possible execution paths */
+    conditionalPaths?: ConditionalPathAnalysis;
+    /** Execution time estimation - predicted duration */
+    timeEstimation?: ExecutionTimeEstimation;
+}
+/**
+ * Data flow prediction for a step
+ * Shows what data flows in and out of each step
+ */
+export interface DataFlowPrediction {
+    /** Step ID */
+    step: string;
+    /** Step name */
+    stepName?: string;
+    /** Input data sources */
+    inputs: {
+        /** Source of the data */
+        source: 'workflow.inputs' | 'step.output' | 'context' | 'secrets' | 'env' | 'static';
+        /** Variable/field key */
+        key: string;
+        /** Source step ID (if from step.output) */
+        sourceStep?: string;
+        /** Inferred type */
+        type?: string;
+        /** Sample value (for static/default values) */
+        example?: any;
+    }[];
+    /** Output data */
+    outputs: {
+        /** Output key */
+        key: string;
+        /** Inferred type */
+        type?: string;
+        /** Steps that consume this output */
+        usedBy: string[];
+    }[];
+    /** Whether this step has unresolved dependencies */
+    hasUnresolvedDependencies: boolean;
+}
+/**
+ * Conditional path analysis
+ * Analyzes all possible execution paths based on conditions
+ */
+export interface ConditionalPathAnalysis {
+    /** Total number of possible paths */
+    totalPaths: number;
+    /** All execution paths */
+    paths: {
+        /** Path description */
+        description: string;
+        /** Conditions that must be true for this path */
+        conditions: string[];
+        /** Steps executed in this path */
+        stepsExecuted: string[];
+        /** Steps skipped in this path */
+        stepsSkipped: string[];
+        /** Likelihood of this path */
+        likelihood: 'always' | 'likely' | 'possible' | 'unlikely' | 'never';
+    }[];
+    /** Steps with conditions */
+    conditionalSteps: {
+        step: string;
+        condition: string;
+        canBeSkipped: boolean;
+    }[];
+    /** Steps that are never reachable */
+    unreachableSteps: string[];
+    /** Steps that always execute */
+    alwaysExecutes: string[];
+}
+/**
+ * Execution time estimation
+ * Predicts how long the workflow will take
+ */
+export interface ExecutionTimeEstimation {
+    /** Total estimated time */
+    total: {
+        /** Best case scenario (ms) */
+        min: number;
+        /** Average expected time (ms) */
+        avg: number;
+        /** Worst case scenario (ms) */
+        max: number;
+    };
+    /** Estimated time by execution phase */
+    byPhase: {
+        /** Phase number */
+        phase: number;
+        /** Steps in this phase */
+        steps: string[];
+        /** Duration estimate (ms) */
+        duration: {
+            min: number;
+            avg: number;
+            max: number;
+        };
+    }[];
+    /** Critical path - longest dependency chain */
+    criticalPath: {
+        /** Steps in the critical path */
+        steps: string[];
+        /** Total duration of critical path (ms) */
+        duration: number;
+    };
+    /** Performance bottlenecks */
+    bottlenecks: {
+        /** Step ID */
+        step: string;
+        /** Reason it's a bottleneck */
+        reason: string;
+        /** Estimated impact if optimized (ms saved) */
+        impact: number;
+    }[];
+    /** Time estimates per step */
+    byStep: {
+        step: string;
+        min: number;
+        avg: number;
+        max: number;
+        /** Whether this step is on the critical path */
+        onCriticalPath: boolean;
+    }[];
+}
+/**
+ * Explanation event - Logged to EngineLogger
+ */
+export interface ExplanationEvent {
+    /** Event type */
+    type: 'explanation';
+    /** Explanation timestamp */
+    timestamp: Date;
+    /** Full explanation */
+    explanation: ExecutionExplanation;
+}
+/**
+ * Known workflow intents
+ */
+export type WorkflowIntent = 'data-pipeline' | 'deployment' | 'testing' | 'monitoring' | 'notification' | 'integration' | 'automation' | 'orchestration' | 'unknown';
+/**
+ * Intent classification confidence
+ */
+export type IntentConfidence = 'high' | 'medium' | 'low';
+/**
+ * Intent classification result
+ */
+export interface ClassifiedIntent {
+    /** Primary intent */
+    intent: WorkflowIntent;
+    /** Classification confidence */
+    confidence: IntentConfidence;
+    /** Secondary intents (if any) */
+    secondaryIntents?: WorkflowIntent[];
+    /** Reasoning (for debugging) */
+    reasoning: string;
+    /** Detected patterns */
+    patterns: string[];
+}
+/**
+ * Intent-based recommendations
+ */
+export interface IntentRecommendations {
+    /** Suggested adapters */
+    suggestedAdapters?: string[];
+    /** Optimization hints */
+    optimizations?: string[];
+    /** Common pitfalls to avoid */
+    warnings?: string[];
+    /** Best practices */
+    bestPractices?: string[];
+}
+/**
+ * Execution strategy types
+ */
+export type ExecutionStrategy = 'default' | 'sequential' | 'aggressive' | 'conservative' | 'fast-fail' | 'resilient';
+/**
+ * Execution context for strategy resolution
+ */
+export interface ExecutionStrategyContext {
+    /** Parsed workflow */
+    workflow: ParsedWorkflow;
+    /** System metrics (future) */
+    systemLoad?: {
+        cpu: number;
+        memory: number;
+        activeWorkflows: number;
+    };
+    /** Workflow intent (from annotations) */
+    intent?: string;
+    /** Resource limits */
+    resourceLimits?: {
+        maxConcurrentSteps: number;
+        maxMemory: number;
+        timeout: number;
+    };
+    /** Historical data (future) */
+    history?: {
+        previousExecutions: number;
+        averageSuccessRate: number;
+        commonFailures: string[];
+    };
+}
+/**
+ * Strategy resolution result
+ */
+export interface ResolvedExecutionStrategy {
+    /** Selected strategy */
+    strategy: ExecutionStrategy;
+    /** Strategy-specific adjustments */
+    adjustments: {
+        /** Concurrency limit */
+        maxConcurrentSteps?: number;
+        /** Timeout multiplier */
+        timeoutMultiplier?: number;
+        /** Retry strategy override */
+        retryStrategy?: 'exponential' | 'linear' | 'constant';
+        /** Max retry attempts */
+        maxRetries?: number;
+        /** Enable caching */
+        enableCaching?: boolean;
+    };
+    /** Reason for strategy selection (for observability) */
+    reason: string;
+}
+/**
+ * Step execution status
+ *
+ * Lifecycle:
+ * PENDING → RUNNING → SUCCESS → COMPLETED
+ * OR
+ * PENDING → RUNNING → FAILED → RETRYING → RUNNING → SUCCESS → COMPLETED
+ * OR
+ * PENDING → SKIPPED
+ */
+export declare enum StepStatus {
+    /** Step is queued, not yet started */
+    PENDING = "PENDING",
+    /** Step is currently executing */
+    RUNNING = "RUNNING",
+    /** Step completed successfully */
+    SUCCESS = "SUCCESS",
+    /** Step failed */
+    FAILED = "FAILED",
+    /** Step is retrying after failure */
+    RETRYING = "RETRYING",
+    /** Step was skipped (conditional execution) */
+    SKIPPED = "SKIPPED",
+    /** Step timed out */
+    TIMEOUT = "TIMEOUT",
+    /** Step was cancelled */
+    CANCELLED = "CANCELLED"
+}
+/**
+ * Workflow execution status
+ */
+export declare enum WorkflowStatus {
+    /** Workflow is queued, not yet started */
+    QUEUED = "QUEUED",
+    /** Workflow is currently executing */
+    RUNNING = "RUNNING",
+    /** Workflow completed successfully (all steps success) */
+    COMPLETED = "COMPLETED",
+    /** Workflow failed (one or more steps failed) */
+    FAILED = "FAILED",
+    /** Workflow partially completed (some steps failed but continueOnError=true) */
+    PARTIAL = "PARTIAL",
+    /** Workflow timed out */
+    TIMEOUT = "TIMEOUT",
+    /** Workflow was cancelled */
+    CANCELLED = "CANCELLED",
+    /** Workflow is paused (future feature) */
+    PAUSED = "PAUSED"
+}
+/**
+ * Step execution state
+ */
+export interface StepExecutionState {
+    /** Unique step ID */
+    stepId: string;
+    /** Current status */
+    status: StepStatus;
+    /** Number of execution attempts */
+    attempts: number;
+    /** Start timestamp (ms since epoch) */
+    startTime?: number;
+    /** End timestamp (ms since epoch) */
+    endTime?: number;
+    /** Error information if failed */
+    error?: {
+        message: string;
+        code?: string;
+        stack?: string;
+    };
+    /** Step output data (if successful) */
+    output?: any;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Last updated timestamp */
+    updatedAt: number;
+}
+/**
+ * Workflow execution state
+ */
+export interface WorkflowExecutionState {
+    /** Unique workflow execution ID */
+    executionId: string;
+    /** Workflow name/ID */
+    workflowId: string;
+    /** Current workflow status */
+    status: WorkflowStatus;
+    /** State of all steps (keyed by step ID) */
+    steps: Record<string, StepExecutionState>;
+    /** Workflow start timestamp (ms since epoch) */
+    startedAt?: number;
+    /** Workflow completion timestamp (ms since epoch) */
+    finishedAt?: number;
+    /** Total workflow duration in milliseconds */
+    duration?: number;
+    /** Workflow-level error (if failed) */
+    error?: {
+        message: string;
+        stepId?: string;
+        code?: string;
+    };
+    /** Execution metadata */
+    metadata: {
+        /** Total number of steps */
+        totalSteps: number;
+        /** Number of completed steps */
+        completedSteps: number;
+        /** Number of failed steps */
+        failedSteps: number;
+        /** Number of skipped steps */
+        skippedSteps: number;
+        /** Current phase being executed */
+        currentPhase?: number;
+        /** Total number of phases */
+        totalPhases?: number;
+    };
+    /** Last state update timestamp */
+    updatedAt: number;
+    /** Execution context snapshot */
+    context?: {
+        env?: Record<string, any>;
+        inputs?: Record<string, any>;
+    };
+}
+/**
+ * State transition record for audit trail
+ */
+export interface StateTransition<T> {
+    /** State before transition */
+    readonly from: T;
+    /** State after transition */
+    readonly to: T;
+    /** Timestamp of transition (ms since epoch) */
+    readonly timestamp: number;
+    /** Optional reason for transition */
+    readonly reason?: string;
+}
+/**
+ * State machine configuration
+ */
+export interface StateMachineConfig<T> {
+    /** Initial state */
+    readonly initialState: T;
+    /** Valid transitions map: from → allowed to states */
+    readonly transitions: ReadonlyMap<T, readonly T[]>;
+    /** Terminal states (no further transitions allowed) */
+    readonly terminalStates: ReadonlySet<T>;
+}
+/**
+ * Permission types for workflow execution
+ */
+export declare enum Permission {
+    HTTP_REQUEST = "http:request",
+    SHELL_EXECUTE = "shell:execute",
+    FILE_READ = "file:read",
+    FILE_WRITE = "file:write",
+    DB_READ = "db:read",
+    DB_WRITE = "db:write",
+    NETWORK_ACCESS = "network:access",
+    SYSTEM_ACCESS = "system:access"
+}
+/**
+ * Reserved top-level workflow fields
+ * These are NEVER user-controlled, always engine-injected
+ */
+export declare const RESERVED_WORKFLOW_FIELDS: readonly ["_internal", "_identity", "_ownership", "_billing", "_usage", "_audit", "_system", "_engine", "_execution", "_runtime", "_security", "_metadata"];
+/**
+ * Reserved context field names
+ * Users cannot set these in workflow context
+ */
+export declare const RESERVED_CONTEXT_FIELDS: readonly ["_internal", "_identity", "_ownership", "_billing", "_usage", "_audit", "_system", "_engine", "_security", "executionId", "runId", "traceId", "userId", "workspaceId", "subscriptionId", "subscriptionTier", "billingId", "billingMode", "pricingTier", "pricingModel", "billingSnapshot"];
+/**
+ * Reserved step field names
+ * Users cannot set these in step definitions
+ */
+export declare const RESERVED_STEP_FIELDS: readonly ["_internal", "_billing", "_usage", "_audit", "executionId", "runId", "stepExecutionId"];
+/**
+ * Reserved annotation prefixes
+ * These annotation namespaces are reserved for engine use
+ */
+export declare const RESERVED_ANNOTATION_PREFIXES: readonly ["engine.", "system.", "internal.", "billing.", "audit.", "security."];
+/**
+ * Security error codes
+ */
+export declare enum SecurityErrorCode {
+    /** User attempted to set a reserved field name */
+    RESERVED_FIELD_OVERRIDE = "ENGINE_RESERVED_FIELD_OVERRIDE",
+    /** User attempted to set billing-related fields */
+    BILLING_FIELD_OVERRIDE = "ENGINE_BILLING_FIELD_OVERRIDE",
+    /** User attempted to set execution identity fields */
+    IDENTITY_FIELD_OVERRIDE = "ENGINE_IDENTITY_FIELD_OVERRIDE",
+    /** User attempted to set ownership fields */
+    OWNERSHIP_FIELD_OVERRIDE = "ENGINE_OWNERSHIP_FIELD_OVERRIDE",
+    /** User attempted to set usage counter fields */
+    USAGE_COUNTER_OVERRIDE = "ENGINE_USAGE_COUNTER_OVERRIDE",
+    /** User attempted to set internal state fields */
+    INTERNAL_STATE_OVERRIDE = "ENGINE_INTERNAL_STATE_OVERRIDE",
+    /** User attempted to use reserved annotation namespace */
+    RESERVED_ANNOTATION_NAMESPACE = "ENGINE_RESERVED_ANNOTATION_NAMESPACE"
+}
+/**
+ * Security violation details (legacy format for backward compatibility)
+ * @deprecated Use SecurityError factory methods instead
+ */
+export interface SecurityViolationDetails {
+    /** Error code for programmatic handling */
+    code: SecurityErrorCode;
+    /** Location where violation occurred */
+    location: string;
+    /** The reserved field that was attempted */
+    field: string;
+    /** The value user tried to set (for debugging) */
+    attemptedValue?: any;
+    /** Why this field is protected */
+    reason: string;
+    /** Suggested fix */
+    suggestion: string;
+}
+/**
+ * Diagnostic error information
+ * Contains all data needed to understand and debug an error
+ */
+export interface OrbytErrorDiagnostic {
+    /** Structured error code (e.g., ORB-S-001) */
+    code: OrbytErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Process exit code from ecosystem-core (for CLI) */
+    exitCode?: ExitCodes;
+    /** Path to the error location (e.g., "workflow.steps[2].uses") */
+    path?: string;
+    /** Optional suggestion for fixing the error */
+    hint?: string;
+    /** Error severity (ERROR, WARNING, INFO) */
+    severity: ErrorSeverity;
+    /** Additional context data for debugging */
+    context?: Record<string, any>;
+}
+/**
+ * Schedule status
+ */
+export type ScheduleStatus = 'active' | 'paused' | 'disabled' | 'expired';
+/**
+ * Extended schedule trigger type for internal scheduling
+ * Includes core TriggerType values and internal scheduling types
+ */
+export type ScheduleTriggerType = TriggerType | 'interval' | 'once';
+/**
+ * Workflow schedule configuration
+ */
+export interface WorkflowSchedule {
+    /** Unique schedule ID */
+    id: string;
+    /** Workflow ID to execute */
+    workflowId: string;
+    /** Schedule name */
+    name?: string;
+    /** Schedule description */
+    description?: string;
+    /** Trigger type */
+    triggerType: ScheduleTriggerType;
+    /** Cron expression (for cron trigger) */
+    cron?: string;
+    /** Interval in milliseconds (for interval trigger) */
+    intervalMs?: number;
+    /** Timezone for schedule (default: UTC) */
+    timezone?: string;
+    /** Schedule status */
+    status: ScheduleStatus;
+    /** When schedule was created */
+    createdAt: Date;
+    /** When schedule was last updated */
+    updatedAt: Date;
+    /** Last execution timestamp */
+    lastRunAt?: Date;
+    /** Next scheduled execution timestamp */
+    nextRunAt?: Date;
+    /** Start date (schedule won't run before this) */
+    startDate?: Date;
+    /** End date (schedule won't run after this) */
+    endDate?: Date;
+    /** Maximum number of executions (undefined = unlimited) */
+    maxExecutions?: number;
+    /** Current execution count */
+    executionCount: number;
+    /** Input data to pass to workflow */
+    input?: Record<string, any>;
+    /** Schedule metadata */
+    metadata?: Record<string, any>;
+    /** Execution options */
+    options?: ScheduleOptions;
+}
+/**
+ * Schedule execution options
+ */
+export interface ScheduleOptions {
+    /** Skip if previous run is still running */
+    skipIfRunning?: boolean;
+    /** Maximum concurrent executions allowed */
+    maxConcurrent?: number;
+    /** Timeout for single execution (ms) */
+    timeoutMs?: number;
+    /** Retry failed executions */
+    retry?: {
+        max: number;
+        delayMs: number;
+    };
+    /** Handle missed runs when scheduler restarts */
+    catchUpMissedRuns?: boolean;
+}
+/**
+ * Schedule execution record
+ */
+export interface ScheduleExecution {
+    /** Execution ID */
+    id: string;
+    /** Schedule ID */
+    scheduleId: string;
+    /** Workflow ID */
+    workflowId: string;
+    /** Scheduled time */
+    scheduledAt: Date;
+    /** Actual start time */
+    startedAt: Date;
+    /** Completion time */
+    completedAt?: Date;
+    /** Execution status */
+    status: 'running' | 'completed' | 'failed' | 'timeout';
+    /** Execution result */
+    result?: any;
+    /** Error if failed */
+    error?: Error;
+    /** Duration in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Schedule creation input
+ */
+export interface CreateScheduleInput {
+    /** Workflow ID */
+    workflowId: string;
+    /** Schedule name */
+    name?: string;
+    /** Description */
+    description?: string;
+    /** Trigger type */
+    triggerType: ScheduleTriggerType;
+    /** Cron expression (required for cron trigger) */
+    cron?: string;
+    /** Interval in milliseconds (required for interval trigger) */
+    intervalMs?: number;
+    /** Timezone for schedule */
+    timezone?: string;
+    /** Start date */
+    startDate?: Date;
+    /** End date */
+    endDate?: Date;
+    /** Max executions */
+    maxExecutions?: number;
+    /** Input data */
+    input?: Record<string, any>;
+    /** Options */
+    options?: ScheduleOptions;
+    /** Event source (for event triggers) */
+    eventSource?: string;
+    /** Webhook endpoint (for webhook triggers) */
+    webhookEndpoint?: string;
+}
+/**
+ * Scheduler configuration
+ */
+export interface CronSchedulerConfig {
+    /** Enable schedule execution (false = dry run mode) */
+    enabled?: boolean;
+    /** Maximum concurrent workflow executions */
+    maxConcurrent?: number;
+    /** Timezone for schedules (default: UTC) */
+    defaultTimezone?: string;
+}
+/**
+ * Schedule trigger callback
+ */
+export type ScheduleTriggerCallback = (schedule: WorkflowSchedule, execution: ScheduleExecution) => Promise<void> | void;
+/**
+ * Scheduler event listeners
+ */
+export interface SchedulerEventListeners {
+    /** Called when schedule is triggered */
+    onScheduleTrigger?: ScheduleTriggerCallback;
+    /** Called when schedule execution completes */
+    onExecutionComplete?: (execution: ScheduleExecution) => void | Promise<void>;
+    /** Called when schedule execution fails */
+    onExecutionFailed?: (execution: ScheduleExecution, error: Error) => void | Promise<void>;
+    /** Called when scheduler starts */
+    onStart?: () => void | Promise<void>;
+    /** Called when scheduler stops */
+    onStop?: () => void | Promise<void>;
+}
+/**
+ * Permission policy for workflow execution
+ */
+export interface PermissionPolicy {
+    /** Allow network access */
+    allowNetwork?: boolean;
+    /** Allow file system access */
+    allowFileSystem?: boolean;
+    /** Allow shell command execution */
+    allowShell?: boolean;
+    /** Allowed adapter types */
+    allowedAdapters?: string[];
+    /** Blocked adapter types */
+    blockedAdapters?: string[];
+    /** Maximum step timeout (ms) */
+    maxStepTimeout?: number;
+    /** Maximum workflow timeout (ms) */
+    maxWorkflowTimeout?: number;
+}
+/**
+ * Sandbox configuration
+ */
+export interface SandboxConfig {
+    /** Policy to enforce */
+    policy: PermissionPolicy;
+    /** Isolated environment variables */
+    env?: Record<string, string>;
+    /** Working directory */
+    cwd?: string;
+}
+/**
+ * Sandbox execution context
+ */
+export interface SandboxContext {
+    /** Sandbox ID */
+    id: string;
+    /** Policy being enforced */
+    policy: PermissionPolicy;
+    /** Start time */
+    startedAt: Date;
+    /** Resource usage tracking */
+    usage: {
+        memory: number;
+        cpu: number;
+        duration: number;
+    };
+}
+/**
+ * Core event interface - all events must conform to this shape
+ */
+export interface OrbytEvent<T = any> {
+    /** Event type identifier */
+    type: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** ID of the workflow execution */
+    workflowId?: string;
+    /** ID of the step being executed */
+    stepId?: string;
+    /** ID of the specific execution run */
+    runId?: string;
+    /** Event-specific payload data */
+    payload?: T;
+}
+/**
+ * Engine-wide event types
+ * These cover all significant lifecycle moments in the execution flow
+ */
+export declare enum EngineEventType {
+    WORKFLOW_STARTED = "workflow.started",
+    WORKFLOW_COMPLETED = "workflow.completed",
+    WORKFLOW_FAILED = "workflow.failed",
+    WORKFLOW_PAUSED = "workflow.paused",
+    WORKFLOW_RESUMED = "workflow.resumed",
+    WORKFLOW_CANCELLED = "workflow.cancelled",
+    STEP_STARTED = "step.started",
+    STEP_COMPLETED = "step.completed",
+    STEP_FAILED = "step.failed",
+    STEP_SKIPPED = "step.skipped",
+    STEP_RETRYING = "step.retrying",
+    STEP_TIMEOUT = "step.timeout",
+    JOB_ENQUEUED = "job.enqueued",
+    JOB_DEQUEUED = "job.dequeued",
+    JOB_RETRY = "job.retry",
+    SCHEDULE_TRIGGERED = "schedule.triggered",
+    TRIGGER_FIRED = "trigger.fired",
+    STATE_CHANGED = "state.changed",
+    ENGINE_STARTED = "engine.started",
+    ENGINE_STOPPED = "engine.stopped",
+    WORKER_ONLINE = "worker.online",
+    WORKER_OFFLINE = "worker.offline"
+}
+/**
+ * Typed event payloads for better type safety
+ */
+export interface WorkflowStartedPayload {
+    workflowId: string;
+    workflowName: string;
+    runId: string;
+    triggeredBy?: string;
+    inputs?: Record<string, any>;
+}
+export interface WorkflowCompletedPayload {
+    workflowId: string;
+    workflowName: string;
+    runId: string;
+    durationMs: number;
+    stepCount: number;
+}
+export interface WorkflowFailedPayload {
+    workflowId: string;
+    workflowName: string;
+    runId: string;
+    error: string;
+    failedStep?: string;
+    durationMs: number;
+}
+export interface StepStartedPayload {
+    workflowId: string;
+    runId: string;
+    stepId: string;
+    stepName: string;
+    adapterType: string;
+}
+export interface StepCompletedPayload {
+    workflowId: string;
+    runId: string;
+    stepId: string;
+    stepName: string;
+    adapterType: string;
+    durationMs: number;
+    output?: any;
+}
+export interface StepFailedPayload {
+    workflowId: string;
+    runId: string;
+    stepId: string;
+    stepName: string;
+    adapterType: string;
+    error: string;
+    attempt: number;
+    willRetry: boolean;
+}
+export interface StepRetryingPayload {
+    workflowId: string;
+    runId: string;
+    stepId: string;
+    stepName: string;
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+}
+export interface JobEnqueuedPayload {
+    jobId: string;
+    workflowId: string;
+    priority: number;
+    queueDepth: number;
+}
+export interface ScheduleTriggeredPayload {
+    scheduleId: string;
+    workflowId: string;
+    triggerType: string;
+    nextRun?: Date;
+}
+export interface StateChangedPayload {
+    workflowId: string;
+    runId: string;
+    from: string;
+    to: string;
+}
+/**
+ * Failure strategy type
+ */
+export type FailureStrategyType = 'abort' | 'continue' | 'skipDependent';
+/**
+ * Failure strategy configuration
+ */
+export interface FailureStrategyConfig {
+    /** Strategy type */
+    type: FailureStrategyType;
+    /** Allow partial workflow completion */
+    allowPartialSuccess?: boolean;
+    /** Maximum number of step failures before aborting workflow */
+    maxFailures?: number;
+    /** Critical step IDs that must succeed (failure = abort) */
+    criticalSteps?: string[];
+    /** Cleanup function to run on failure */
+    onFailure?: (stepId: string, error: Error) => Promise<void> | void;
+}
+/**
+ * Failure decision for a specific step failure
+ */
+export interface FailureDecision {
+    /** Should workflow continue? */
+    continueWorkflow: boolean;
+    /** Should execute cleanup? */
+    runCleanup: boolean;
+    /** Should skip dependent steps? */
+    skipDependentSteps: boolean;
+    /** Reason for decision */
+    reason: string;
+    /** Final workflow status if abort */
+    finalStatus?: 'failed' | 'partial';
+}
+/**
+ * Failure context for tracking execution state
+ */
+export interface FailureContext {
+    /** ID of failed step */
+    stepId: string;
+    /** Error that caused failure */
+    error: Error;
+    /** Total steps in workflow */
+    totalSteps: number;
+    /** Number of completed steps */
+    completedSteps: number;
+    /** Number of failed steps so far */
+    failureCount: number;
+    /** Workflow execution ID */
+    executionId?: string;
+}
+/**
+ * Failure handling result
+ */
+export interface FailureHandlingResult {
+    /** Failure decision */
+    decision: FailureDecision;
+    /** Cleanup completed successfully */
+    cleanupSuccess: boolean;
+    /** Error during cleanup (if any) */
+    cleanupError?: Error;
+    /** Steps to skip based on decision */
+    stepsToSkip: string[];
+}
+/**
+ * Failure event listeners
+ */
+export interface FailureListeners {
+    /** Called before handling failure */
+    onBeforeHandle?: (context: FailureContext) => void | Promise<void>;
+    /** Called after decision is made */
+    onDecision?: (decision: FailureDecision, context: FailureContext) => void | Promise<void>;
+    /** Called before cleanup */
+    onBeforeCleanup?: (context: FailureContext) => void | Promise<void>;
+    /** Called after cleanup */
+    onAfterCleanup?: (success: boolean, context: FailureContext) => void | Promise<void>;
+    /** Called when workflow should abort */
+    onAbort?: (reason: string, context: FailureContext) => void | Promise<void>;
+    /** Called when workflow continues after failure */
+    onContinue?: (context: FailureContext) => void | Promise<void>;
+}
+/**
+ * Dependency information for skip decisions
+ */
+export interface DependencyInfo {
+    /** Step ID to dependencies map */
+    stepDependencies: Map<string, string[]>;
+    /** Step ID to dependents map (reverse) */
+    stepDependents: Map<string, string[]>;
 }
 //# sourceMappingURL=core-types.d.ts.map