reqon-dsl 0.2.0 → 0.4.0

package/dist/interpreter/executor.js

@@ -1,50 +1,104 @@
+/**
+ * ---
+ * purpose: Mission executor - orchestrates pipeline execution
+ * inputs:
+ *   - ReqonProgram - parsed AST
+ *   - ExecutorConfig - auth, stores, callbacks, debug settings
+ * outputs:
+ *   - ExecutionResult - success/errors, stores, duration
+ * related:
+ *   - ./context.ts - execution state (variables, stores, sources)
+ *   - ./evaluator.ts - expression evaluation
+ *   - ./fetch-handler.ts - HTTP requests
+ *   - ./step-handlers/ - individual step type handlers
+ *   - ./source-manager.ts - auth provider management
+ * ---
+ */
 import { isParallelStage } from '../ast/nodes.js';
-import { createContext, setVariable } from './context.js';
+import { createContext, childContext, setVariable } from './context.js';
+import { createHash } from 'node:crypto';
 import { evaluate } from './evaluator.js';
-import { HttpClient, BearerAuthProvider, OAuth2AuthProvider } from './http.js';
-import { createStore, resolveStoreType } from '../stores/index.js';
-import { loadOAS } from '../oas/index.js';
+import { SourceManager } from './source-manager.js';
+import { StoreManager } from './store-manager.js';
 import { AdaptiveRateLimiter } from '../auth/rate-limiter.js';
 import { CircuitBreaker } from '../auth/circuit-breaker.js';
 import { createExecutionState, findResumePoint, FileExecutionStore, } from '../execution/index.js';
-import { FileSyncStore, } from '../sync/index.js';
+import { FileSyncStore, LogBackedSyncStore } from '../sync/index.js';
 import { FetchHandler } from './fetch-handler.js';
-import { ForHandler, MapHandler, ValidateHandler, StoreHandler, MatchHandler, WebhookHandler, SkipSignal, RetrySignal, JumpSignal, QueueSignal, } from './step-handlers/index.js';
+import { ForHandler, MapHandler, ValidateHandler, StoreHandler, MatchHandler, ApplyHandler, WebhookHandler, PauseHandler, SkipSignal, AbortError, RetrySignal, JumpSignal, QueueSignal, } from './step-handlers/index.js';
+import { createStructuredLogger } from '../observability/index.js';
+import { PauseSignal } from './signals.js';
+import { FileTraceStore, createTraceRecorder, } from '../trace/index.js';
+import { FilePauseStore, LogBackedPauseStore, createPauseManager, } from '../pause/index.js';
+import { sleep } from '../utils/async.js';
+import { redactNamedValue } from '../utils/redact.js';
+import { effectId, loadState } from '../execution-log/index.js';
+import { generateExecutionId } from '../execution/index.js';
+/** Max parallel-stage actions running concurrently (bounds fan-out). */
+const MAX_PARALLEL_ACTIONS = 8;
 export class MissionExecutor {
     config;
     ctx;
     errors = [];
     actionsRun = [];
-    oasSources = new Map();
-    sourceConfigs = new Map();
+    /** Monotonic key generator for queued values lacking an id. */
+    queueCounter = 0;
+    transforms = new Map();
     rateLimiter;
     circuitBreaker;
+    sourceManager;
+    storeManager;
     executionStore;
     executionState;
     syncStore;
     missionName;
+    eventEmitter;
+    logger;
+    executionLog;
+    /** Stable id used for the execution event log (independent of persistState). */
+    logExecutionId;
+    /** Effect ids already applied (from the log) — replay skips these. */
+    appliedEffects = new Set();
+    /** Backfill page progress per step id (from the log) — resumes pagination. */
+    pageProgress = new Map();
+    /** The pause being resumed on this run — its step replays past, not into, a pause. */
+    resumingPause;
+    debugController;
+    traceRecorder;
+    traceStore;
+    pauseManager;
+    pauseStore;
+    currentStageIndex = 0;
+    currentPauseId;
     constructor(config = {}) {
         this.config = config;
         this.ctx = createContext();
         this.rateLimiter = new AdaptiveRateLimiter();
         this.circuitBreaker = new CircuitBreaker();
+        // Initialize managers (logger set after verbose callbacks configured)
+        this.sourceManager = new SourceManager({ auth: config.auth, missionDir: config.missionDir }, { rateLimiter: this.rateLimiter, circuitBreaker: this.circuitBreaker });
+        this.storeManager = new StoreManager({
+            customStores: config.stores,
+            developmentMode: config.developmentMode,
+            dataDir: config.dataDir,
+        });
         // Set up rate limit callbacks with default logging if verbose
         const callbacks = config.rateLimitCallbacks ?? {};
         if (config.verbose && !callbacks.onRateLimited) {
             callbacks.onRateLimited = (event) => {
-                console.log(`[Reqon] Rate limited on ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
+                this.log(`Rate limited on ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
                     `waiting ${event.waitSeconds}s (strategy: ${event.strategy})`);
             };
         }
         if (config.verbose && !callbacks.onResumed) {
             callbacks.onResumed = (event) => {
-                console.log(`[Reqon] Rate limit cleared for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} ` +
+                this.log(`Rate limit cleared for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} ` +
                     `(waited ${event.waitedSeconds}s)`);
             };
         }
         if (config.verbose && !callbacks.onWaiting) {
             callbacks.onWaiting = (event) => {
-                console.log(`[Reqon] Still waiting for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
+                this.log(`Still waiting for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
                     `${event.waitSeconds}s remaining (elapsed: ${event.elapsedSeconds}s)`);
             };
         }
@@ -53,33 +107,78 @@ export class MissionExecutor {
         const cbCallbacks = config.circuitBreakerCallbacks ?? {};
         if (config.verbose && !cbCallbacks.onOpen) {
             cbCallbacks.onOpen = (event) => {
-                console.log(`[Reqon] Circuit breaker OPEN for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
+                this.log(`Circuit breaker OPEN for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
                     `${event.failures} failures (${event.reason ?? 'threshold exceeded'})`);
             };
         }
         if (config.verbose && !cbCallbacks.onHalfOpen) {
             cbCallbacks.onHalfOpen = (event) => {
-                console.log(`[Reqon] Circuit breaker HALF-OPEN for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
+                this.log(`Circuit breaker HALF-OPEN for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
                     `testing recovery`);
             };
         }
         if (config.verbose && !cbCallbacks.onClose) {
             cbCallbacks.onClose = (event) => {
-                console.log(`[Reqon] Circuit breaker CLOSED for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
+                this.log(`Circuit breaker CLOSED for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
                     `recovery successful`);
             };
         }
         if (config.verbose && !cbCallbacks.onRejected) {
             cbCallbacks.onRejected = (event) => {
-                console.log(`[Reqon] Request REJECTED by circuit breaker for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
+                this.log(`Request REJECTED by circuit breaker for ${event.source}${event.endpoint ? `:${event.endpoint}` : ''} - ` +
                     `retry in ${Math.ceil(event.nextAttemptIn / 1000)}s`);
             };
         }
         this.circuitBreaker.setCallbacks(cbCallbacks);
         // Initialize execution store if persistence enabled
         if (config.persistState) {
-            this.executionStore = config.executionStore ?? new FileExecutionStore(`${config.dataDir ?? '.reqon-data'}/executions`);
+            this.executionStore =
+                config.executionStore ??
+                    new FileExecutionStore(`${config.dataDir ?? '.reqon-data'}/executions`);
+        }
+        // Initialize event emitter if provided
+        this.eventEmitter = config.eventEmitter;
+        this.executionLog = config.executionLog;
+        // Initialize logger if verbose or provided
+        if (config.logger) {
+            this.logger = config.logger;
+        }
+        else if (config.verbose) {
+            this.logger = createStructuredLogger({
+                prefix: 'Reqon',
+                level: 'debug',
+                context: {},
+            });
         }
+        // Update managers with log function now that logger is configured
+        this.sourceManager = new SourceManager({ auth: config.auth, missionDir: config.missionDir, log: (msg) => this.log(msg) }, { rateLimiter: this.rateLimiter, circuitBreaker: this.circuitBreaker });
+        this.storeManager = new StoreManager({
+            customStores: config.stores,
+            developmentMode: config.developmentMode,
+            dataDir: config.dataDir,
+            log: (msg) => this.log(msg),
+        });
+        // Initialize debug controller if provided
+        this.debugController = config.debugController;
+        // Initialize trace store
+        this.traceStore =
+            config.traceStore ?? new FileTraceStore(`${config.dataDir ?? '.reqon-data'}/traces`);
+        // Initialize pause store and manager. In durable mode the execution log is
+        // the single source of truth — pause state (deadline, triggers, checkpoint)
+        // is recorded as pause events and folded back, rather than kept in a
+        // separate pause file.
+        this.pauseStore =
+            config.pauseStore ??
+                (config.executionLog
+                    ? new LogBackedPauseStore(config.executionLog)
+                    : new FilePauseStore(`${config.dataDir ?? '.reqon-data'}/pauses`));
+        this.pauseManager =
+            config.pauseManager ??
+                createPauseManager({
+                    store: this.pauseStore,
+                    webhookServer: config.webhookServer,
+                    log: (msg) => this.log(msg),
+                });
     }
     async execute(program) {
         const startTime = Date.now();
@@ -96,6 +195,54 @@ export class MissionExecutor {
         }
         // Initialize or resume execution state
         await this.initializeExecutionState(mission);
+        // Establish a stable id for the execution log. On resume we reuse the prior
+        // id (so replay reads the same log); otherwise a fresh id.
+        this.logExecutionId =
+            this.executionState?.id ?? this.config.resumeFrom ?? generateExecutionId();
+        // Load already-applied effects from the log so replay skips them, and note
+        // a pending pause so we can record its resumption below.
+        let pendingPauseId;
+        let alreadyResumedPauseId;
+        if (this.executionLog) {
+            const prior = await loadState(this.executionLog, this.logExecutionId);
+            this.appliedEffects = new Set(prior.appliedEffects);
+            this.pageProgress = prior.pageProgress;
+            pendingPauseId = prior.pendingPauseId;
+            // A resume trigger may have recorded `pause.resumed` already; if the run
+            // didn't finish, we still need to replay past that pause.
+            alreadyResumedPauseId = prior.pendingPauseId ? undefined : prior.resumedPauseId;
+        }
+        await this.logEvent({ type: 'mission.started', mission: mission.name });
+        // If the prior log ended paused, this run is resuming that pause. Record it
+        // so the log's folded status leaves 'paused' before replay continues, and
+        // load the pause's checkpoint so the replayed pause step resumes past it
+        // (restoring captured state) rather than pausing again.
+        if (pendingPauseId) {
+            await this.logEvent({
+                type: 'pause.resumed',
+                pauseId: pendingPauseId,
+                resumedBy: this.config.resumeFrom ? 'resume' : 'replay',
+            });
+            this.resumingPause = await this.loadResumingPause(pendingPauseId);
+        }
+        else if (alreadyResumedPauseId) {
+            // The pause was already marked resumed out of band (by a webhook/timeout
+            // trigger) but the run didn't continue past it. Replay past it now without
+            // recording a second `pause.resumed` — otherwise the step re-pauses forever.
+            this.resumingPause = await this.loadResumingPause(alreadyResumedPauseId);
+        }
+        // Initialize trace recorder if tracing is enabled
+        if (mission.trace && this.traceStore && this.executionState) {
+            this.traceRecorder = createTraceRecorder({
+                executionId: this.executionState.id,
+                mission: mission.name,
+                mode: mission.trace.mode,
+                store: this.traceStore,
+                metadata: this.config.metadata,
+                streaming: true, // Stream snapshots as they happen
+            });
+            this.log(`Tracing enabled (mode: ${mission.trace.mode})`);
+        }
         try {
             await this.executeMission(mission);
             // Mark execution as completed
@@ -105,24 +252,44 @@ export class MissionExecutor {
                 this.executionState.duration = Date.now() - startTime;
                 await this.saveExecutionState();
             }
+            await this.logEvent({ type: 'mission.completed' });
         }
         catch (error) {
-            this.errors.push({
-                action: 'mission',
-                step: 'execute',
-                message: error.message,
-                details: error,
-            });
-            // Mark execution as failed
-            if (this.executionState) {
-                this.executionState.status = 'failed';
-                this.executionState.completedAt = new Date();
-                this.executionState.duration = Date.now() - startTime;
-                await this.saveExecutionState();
+            // PauseSignal is not an error - execution was intentionally paused
+            if (error instanceof PauseSignal) {
+                this.log('Execution paused');
+                this.currentPauseId = error.pauseId;
+                // State is already set to 'paused' in checkPause() or pause handler
+                // Don't record as error, just let execution end.
+                //
+                // A LogBackedPauseStore already appended pause.created (with the full
+                // pause payload) when the pause manager saved it, so only emit the bare
+                // event here when the pause store is *not* the log itself — otherwise
+                // we'd record the pause twice.
+                if (error.pauseId && !(this.pauseStore instanceof LogBackedPauseStore)) {
+                    await this.logEvent({ type: 'pause.created', pauseId: error.pauseId });
+                }
+            }
+            else {
+                this.errors.push({
+                    action: 'mission',
+                    step: 'execute',
+                    message: error.message,
+                    details: error,
+                });
+                // Mark execution as failed
+                if (this.executionState) {
+                    this.executionState.status = 'failed';
+                    this.executionState.completedAt = new Date();
+                    this.executionState.duration = Date.now() - startTime;
+                    await this.saveExecutionState();
+                }
+                await this.logEvent({ type: 'mission.failed', error: error.message });
             }
         }
         const duration = Date.now() - startTime;
-        const success = this.errors.length === 0;
+        const isPaused = this.executionState?.status === 'paused';
+        const success = this.errors.length === 0 && !isPaused;
         // Emit onExecutionComplete callback - count stages in a single pass
         const stageCounts = this.executionState?.stages.reduce((acc, s) => {
             if (s.status === 'completed')
@@ -142,14 +309,44 @@ export class MissionExecutor {
             stagesFailed,
             errors: this.errors,
         });
+        // Emit mission.complete, mission.paused, or mission.failed event
+        if (isPaused) {
+            this.eventEmitter?.emit('mission.paused', {
+                stagesCompleted,
+                executionId: this.executionState?.id,
+            });
+        }
+        else if (success) {
+            this.eventEmitter?.emit('mission.complete', {
+                success: true,
+                stagesCompleted,
+                stagesFailed,
+                stagesSkipped: this.executionState?.stages.filter((s) => s.status === 'skipped').length ?? 0,
+                errorCount: this.errors.length,
+            });
+        }
+        else {
+            const failedStage = this.executionState?.stages.find((s) => s.status === 'failed');
+            this.eventEmitter?.emit('mission.failed', {
+                error: this.errors[0]?.message ?? 'Unknown error',
+                failedStage: failedStage?.action,
+                stagesCompleted,
+            });
+        }
+        // Finalize trace if enabled
+        if (this.traceRecorder) {
+            await this.traceRecorder.finalize(success);
+        }
         return {
             success,
             duration,
             actionsRun: this.actionsRun,
             errors: this.errors,
             stores: this.ctx.stores,
-            executionId: this.executionState?.id,
+            executionId: this.executionState?.id ?? this.logExecutionId,
             state: this.executionState,
+            traceId: this.traceRecorder ? this.executionState?.id : undefined,
+            pauseId: this.currentPauseId,
         };
     }
     async initializeExecutionState(mission) {
@@ -190,6 +387,13 @@ export class MissionExecutor {
             isResume,
             metadata: this.config.metadata,
         });
+        // Emit mission.start event
+        this.eventEmitter?.emit('mission.start', {
+            stageCount: mission.pipeline.stages.length,
+            isResume,
+            resumeFromStage: isResume ? findResumePoint(this.executionState) : undefined,
+            metadata: this.config.metadata,
+        });
     }
     async saveExecutionState() {
         if (this.executionStore && this.executionState) {
@@ -226,21 +430,28 @@ export class MissionExecutor {
     async executeMission(mission) {
         this.log(`Executing mission: ${mission.name}`);
         this.missionName = mission.name;
-        // Initialize sync store
-        this.syncStore = this.config.syncStore ?? new FileSyncStore(mission.name, `${this.config.dataDir ?? '.reqon-data'}/sync`);
-        // Initialize sources (HTTP clients)
-        for (const source of mission.sources) {
-            await this.initializeSource(source);
-        }
-        // Initialize stores
-        for (const store of mission.stores) {
-            await this.initializeStore(store);
-        }
+        // Initialize sync store. In durable mode the execution log is the single
+        // source of truth, so sync checkpoints are read back as a view over the log
+        // rather than from a separate sync file.
+        this.syncStore =
+            this.config.syncStore ??
+                (this.executionLog
+                    ? new LogBackedSyncStore(this.executionLog, mission.name)
+                    : new FileSyncStore(mission.name, `${this.config.dataDir ?? '.reqon-data'}/sync`));
+        // Initialize sources using SourceManager
+        await this.sourceManager.initializeSources(mission.sources, this.ctx);
+        // Initialize stores using StoreManager
+        await this.storeManager.initializeStores(mission.stores, this.ctx);
         // Initialize schemas (for match step schema matching)
         for (const schema of mission.schemas) {
             this.ctx.schemas.set(schema.name, schema);
             this.log(`Registered schema: ${schema.name}`);
         }
+        // Initialize transforms
+        for (const transform of mission.transforms) {
+            this.transforms.set(transform.name, transform);
+            this.log(`Registered transform: ${transform.name}`);
+        }
         // Build action lookup
         const actions = new Map();
         for (const action of mission.actions) {
@@ -256,6 +467,8 @@ export class MissionExecutor {
         // Execute pipeline
         for (let i = 0; i < mission.pipeline.stages.length; i++) {
             const stage = mission.pipeline.stages[i];
+            // Check for pause request at safe point (between stages)
+            await this.checkPause();
             // Skip already completed stages when resuming
             if (i < resumeIndex) {
                 this.log(`Skipping ${this.getStageName(stage)} (already completed)`);
@@ -268,16 +481,37 @@ export class MissionExecutor {
                     this.log(`Skipping ${this.getStageName(stage)} (condition not met)`);
                     this.updateStageState(i, { status: 'skipped' });
                     await this.saveExecutionState();
+                    this.updateControlServerState();
                     continue;
                 }
             }
+            // Track current stage index for pause handler
+            this.currentStageIndex = i;
             // Execute stage (parallel or sequential)
-            if (isParallelStage(stage)) {
-                await this.executeParallelStage(i, stage, actions, mission);
+            try {
+                if (isParallelStage(stage)) {
+                    await this.executeParallelStage(i, stage, actions, mission);
+                }
+                else if (stage.action) {
+                    await this.executeSequentialStage(i, stage.action, actions, mission);
+                }
             }
-            else if (stage.action) {
-                await this.executeSequentialStage(i, stage.action, actions, mission);
+            catch (error) {
+                // A jump directive redirects the pipeline to a named action's stage.
+                if (error instanceof JumpSignal) {
+                    const targetIndex = mission.pipeline.stages.findIndex((s) => !isParallelStage(s) && s.action === error.action);
+                    if (targetIndex === -1) {
+                        throw new Error(`Jump target action not found in pipeline: ${error.action}`);
+                    }
+                    this.log(`Jump to action '${error.action}' (stage ${targetIndex})`);
+                    i = targetIndex - 1; // loop's i++ lands on the target stage
+                    this.updateControlServerState();
+                    continue;
+                }
+                throw error;
             }
+            // Update control server with latest state after each stage
+            this.updateControlServerState();
         }
     }
     getStageName(stage) {
@@ -303,6 +537,13 @@ export class MissionExecutor {
             stageName: actionName,
             totalStages: mission.pipeline.stages.length,
         });
+        // Emit stage.start event
+        this.eventEmitter?.emit('stage.start', {
+            stageIndex,
+            stageName: actionName,
+            totalStages: mission.pipeline.stages.length,
+            isParallel: false,
+        });
         try {
             await this.executeAction(action);
             this.actionsRun.push(action.name);
@@ -319,8 +560,19 @@ export class MissionExecutor {
                 success: true,
                 duration: Date.now() - stageStartTime,
             });
+            // Emit stage.complete event
+            this.eventEmitter?.emit('stage.complete', {
+                stageIndex,
+                stageName: actionName,
+                success: true,
+            });
         }
         catch (error) {
+            // A jump directive is flow control, not a stage failure — let it bubble
+            // to the mission loop without polluting stage state.
+            if (error instanceof JumpSignal) {
+                throw error;
+            }
             // Mark stage as failed
             this.updateStageState(stageIndex, {
                 status: 'failed',
@@ -338,9 +590,49 @@ export class MissionExecutor {
                 duration: Date.now() - stageStartTime,
                 error: error.message,
             });
+            // Emit stage.complete event (failure)
+            this.eventEmitter?.emit('stage.complete', {
+                stageIndex,
+                stageName: actionName,
+                success: false,
+                error: error.message,
+            });
             throw error; // Re-throw to stop execution
         }
     }
+    /**
+     * Run all settled-style tasks with a bounded number in flight at once,
+     * preserving result order. Caps fan-out so a wide `run [...]` can't open an
+     * unbounded number of concurrent HTTP/store operations.
+     */
+    async settleWithLimit(tasks, limit) {
+        const results = new Array(tasks.length);
+        let next = 0;
+        const worker = async () => {
+            for (let i = next++; i < tasks.length; i = next++) {
+                try {
+                    results[i] = { status: 'fulfilled', value: await tasks[i]() };
+                }
+                catch (reason) {
+                    results[i] = { status: 'rejected', reason };
+                }
+            }
+        };
+        const workerCount = Math.min(Math.max(1, limit), tasks.length);
+        await Promise.all(Array.from({ length: workerCount }, () => worker()));
+        return results;
+    }
+    /**
+     * Execute a `run [A, B, ...]` stage.
+     *
+     * Failure semantics are **complete-then-fail**: every branch runs to
+     * completion (bounded by MAX_PARALLEL_ACTIONS in flight), then the stage
+     * fails if any branch failed. There is no cancellation of siblings and no
+     * rollback — a branch that committed store writes keeps them even if another
+     * branch failed. Each branch gets its own action scope (step counter +
+     * checkpoints); stores/sources/schemas are shared, so parallel branches that
+     * write the same key get last-writer-wins and should target disjoint keys.
+     */
     async executeParallelStage(stageIndex, stage, actions, mission) {
         const actionNames = stage.actions;
         const stageName = `[${actionNames.join(', ')}]`;
@@ -365,10 +657,19 @@ export class MissionExecutor {
             stageName,
             totalStages: mission.pipeline.stages.length,
         });
+        // Emit stage.start event (parallel)
+        this.eventEmitter?.emit('stage.start', {
+            stageIndex,
+            stageName,
+            totalStages: mission.pipeline.stages.length,
+            isParallel: true,
+            parallelActions: actionNames,
+        });
         this.log(`Executing parallel stage: ${stageName}`);
         try {
-            // Execute all actions in parallel
-            const results = await Promise.allSettled(actionDefs.map(action => this.executeAction(action)));
+            // Execute all actions in parallel, bounded to MAX_PARALLEL_ACTIONS in
+            // flight. allSettled semantics: every started branch runs to completion.
+            const results = await this.settleWithLimit(actionDefs.map((action) => () => this.executeAction(action)), MAX_PARALLEL_ACTIONS);
             // Check for failures
             const failures = [];
             for (let i = 0; i < results.length; i++) {
@@ -381,7 +682,7 @@ export class MissionExecutor {
                 }
             }
             if (failures.length > 0) {
-                const errorMsg = failures.map(f => `${f.name}: ${f.error.message}`).join('; ');
+                const errorMsg = failures.map((f) => `${f.name}: ${f.error.message}`).join('; ');
                 throw new Error(`Parallel stage failed: ${errorMsg}`);
             }
             // Mark stage as completed
@@ -397,6 +698,12 @@ export class MissionExecutor {
                 success: true,
                 duration: Date.now() - stageStartTime,
             });
+            // Emit stage.complete event (success)
+            this.eventEmitter?.emit('stage.complete', {
+                stageIndex,
+                stageName,
+                success: true,
+            });
         }
         catch (error) {
             // Mark stage as failed
@@ -416,154 +723,219 @@ export class MissionExecutor {
                 duration: Date.now() - stageStartTime,
                 error: error.message,
             });
+            // Emit stage.complete event (failure)
+            this.eventEmitter?.emit('stage.complete', {
+                stageIndex,
+                stageName,
+                success: false,
+                error: error.message,
+            });
             throw error; // Re-throw to stop execution
         }
     }
-    async initializeSource(source) {
-        // Store source config for later reference
-        this.sourceConfigs.set(source.name, source);
-        const authConfig = this.config.auth?.[source.name];
-        let authProvider;
-        if (authConfig) {
-            if (authConfig.type === 'bearer' && authConfig.token) {
-                authProvider = new BearerAuthProvider(authConfig.token);
-            }
-            else if (authConfig.type === 'oauth2' && authConfig.accessToken) {
-                authProvider = new OAuth2AuthProvider({
-                    accessToken: authConfig.accessToken,
-                    refreshToken: authConfig.refreshToken,
-                    tokenEndpoint: authConfig.tokenEndpoint,
-                    clientId: authConfig.clientId,
-                    clientSecret: authConfig.clientSecret,
-                });
-            }
-        }
-        // If source has OAS spec, load it
-        let baseUrl = source.config.base;
-        if (source.specPath) {
+    async executeAction(action) {
+        this.log(`Executing action: ${action.name}`);
+        // Flow-control directives surface as thrown signals from a step (typically
+        // a `match` arm). Handle them at the action boundary: skip stops the rest
+        // of the action, queue stashes a value and stops, retry re-runs the whole
+        // action with backoff. Jump/Pause propagate to the mission loop.
+        const MAX_RETRY_FALLBACK = 3;
+        let attempt = 0;
+        for (;;) {
+            // Create a child context for this action with its own response scope and
+            // its own action scope (step counter + deferred checkpoints). Each attempt
+            // gets a fresh scope, so a retry's fetch doesn't double-record and so
+            // parallel actions never share a counter or checkpoint list.
+            const actionCtx = childContext(this.ctx);
+            actionCtx.actionScope = { stepIndex: 0, attempt, pendingCheckpoints: [] };
             try {
-                const oasSource = await loadOAS(source.specPath);
-                this.oasSources.set(source.name, oasSource);
-                // Use base URL from OAS if not explicitly provided
-                if (!baseUrl) {
-                    baseUrl = oasSource.baseUrl;
+                for (const step of action.steps) {
+                    await this.executeStep(step, action.name, actionCtx);
                 }
-                this.log(`Loaded OAS spec for ${source.name}: ${oasSource.operations.size} operations`);
+                // Flush checkpoints for fetches that completed without a later store.
+                await this.flushPendingCheckpoints(actionCtx);
+                return;
             }
             catch (error) {
-                throw new Error(`Failed to load OAS spec for ${source.name}: ${error.message}`);
+                if (error instanceof SkipSignal) {
+                    this.log(`Action ${action.name}: skip — remaining steps skipped`);
+                    await this.flushPendingCheckpoints(actionCtx);
+                    return;
+                }
+                if (error instanceof QueueSignal) {
+                    await this.handleQueue(error);
+                    await this.flushPendingCheckpoints(actionCtx);
+                    return;
+                }
+                if (error instanceof RetrySignal) {
+                    const maxAttempts = error.backoff?.maxAttempts ?? MAX_RETRY_FALLBACK;
+                    attempt++;
+                    if (attempt >= maxAttempts) {
+                        throw new Error(`Action ${action.name} exhausted ${maxAttempts} retry attempt(s)`);
+                    }
+                    const delay = this.computeRetryDelay(error.backoff, attempt);
+                    this.log(`Action ${action.name}: retry ${attempt}/${maxAttempts} in ${delay}ms`);
+                    if (delay > 0)
+                        await sleep(delay);
+                    continue;
+                }
+                // JumpSignal, PauseSignal, and real errors propagate. The action's
+                // checkpoints live on actionCtx and are simply discarded (never flushed)
+                // since the data was not durably stored.
+                throw error;
             }
         }
-        if (!baseUrl) {
-            throw new Error(`Source ${source.name} has no base URL (provide 'base' or OAS spec with servers)`);
+    }
+    /** Compute a retry backoff delay from a RetrySignal's backoff config. */
+    computeRetryDelay(backoff, attempt) {
+        const initial = backoff?.initialDelay ?? 0;
+        switch (backoff?.backoff) {
+            case 'exponential':
+                return initial * Math.pow(2, attempt - 1);
+            case 'linear':
+                return initial * attempt;
+            default:
+                return initial;
         }
-        // Configure rate limiter for this source
-        if (source.config.rateLimit) {
-            this.rateLimiter.configure(source.name, {
-                strategy: source.config.rateLimit.strategy,
-                maxWait: source.config.rateLimit.maxWait,
-                fallbackRpm: source.config.rateLimit.fallbackRpm,
-            });
-            this.log(`Rate limit config for ${source.name}: strategy=${source.config.rateLimit.strategy ?? 'pause'}, ` +
-                `maxWait=${source.config.rateLimit.maxWait ?? 300}s`);
-        }
-        // Configure circuit breaker for this source
-        if (source.config.circuitBreaker) {
-            this.circuitBreaker.configure(source.name, {
-                failureThreshold: source.config.circuitBreaker.failureThreshold,
-                // Convert seconds to milliseconds for the circuit breaker
-                resetTimeout: source.config.circuitBreaker.resetTimeout
-                    ? source.config.circuitBreaker.resetTimeout * 1000
-                    : undefined,
-                successThreshold: source.config.circuitBreaker.successThreshold,
-                failureWindow: source.config.circuitBreaker.failureWindow
-                    ? source.config.circuitBreaker.failureWindow * 1000
-                    : undefined,
-            });
-            this.log(`Circuit breaker config for ${source.name}: ` +
-                `failureThreshold=${source.config.circuitBreaker.failureThreshold ?? 5}, ` +
-                `resetTimeout=${source.config.circuitBreaker.resetTimeout ?? 30}s`);
-        }
-        const client = new HttpClient({
-            baseUrl,
-            auth: authProvider,
-            rateLimiter: this.rateLimiter,
-            circuitBreaker: this.circuitBreaker,
-            sourceName: source.name,
-        });
-        this.ctx.sources.set(source.name, client);
-        this.log(`Initialized source: ${source.name}`);
-    }
-    async initializeStore(store) {
-        // Check for custom store adapter
-        if (this.config.stores?.[store.name]) {
-            this.ctx.stores.set(store.name, this.config.stores[store.name]);
-            this.log(`Initialized store: ${store.name} (custom adapter)`);
+    }
+    /** Push a queued value to its target store (queue directive). */
+    async handleQueue(signal) {
+        const target = signal.target;
+        if (!target) {
+            this.log('Queue directive without target — value discarded');
             return;
         }
-        // Use store factory to create appropriate adapter
-        const developmentMode = this.config.developmentMode ?? true;
-        const storeType = resolveStoreType(store.storeType, developmentMode);
-        const adapter = createStore({
-            type: storeType,
-            name: store.target,
-            baseDir: this.config.dataDir,
-        });
-        this.ctx.stores.set(store.name, adapter);
-        this.log(`Initialized store: ${store.name} (${storeType}${storeType !== store.storeType ? ` <- ${store.storeType}` : ''})`);
-    }
-    async executeAction(action) {
-        this.log(`Executing action: ${action.name}`);
-        for (const step of action.steps) {
-            await this.executeStep(step, action.name);
+        const store = this.ctx.stores.get(target);
+        if (!store) {
+            throw new Error(`Queue target store not found: ${target}`);
         }
+        const value = signal.value;
+        const record = value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : { value };
+        const key = typeof record.id === 'string' || typeof record.id === 'number'
+            ? String(record.id)
+            : `queued-${this.queueCounter++}`;
+        await store.set(key, record);
+        this.log(`Queued value to store '${target}' (key=${key})`);
     }
     async executeStep(step, actionName, ctx) {
         // Use provided context or default to this.ctx
+        // NOTE: ctx is used for action-scoped operations (response, variables)
+        // this.ctx is still used for mission-level resources (stores, sources)
         const execCtx = ctx ?? this.ctx;
-        const originalCtx = this.ctx;
-        // Temporarily use the provided context
-        if (ctx) {
-            this.ctx = ctx;
+        // Track step index per-action so parallel actions don't share a counter.
+        const scope = this.scopeFor(execCtx);
+        const currentStepIndex = scope.stepIndex++;
+        const stepType = this.getStepType(step.type);
+        // Stable step identity for the execution log: action + per-action index.
+        const stepId = `${actionName}#${currentStepIndex}`;
+        // Emit step.start event
+        this.eventEmitter?.emit('step.start', {
+            actionName,
+            stepIndex: currentStepIndex,
+            stepType,
+        });
+        // Append step.started to the durable execution log.
+        await this.logEvent({
+            type: 'step.started',
+            stepId,
+            action: actionName,
+            stepType,
+            attempt: scope.attempt,
+        });
+        const stepStartTime = Date.now();
+        // Record trace snapshot before step
+        if (this.traceRecorder) {
+            await this.traceRecorder.recordBeforeStep(actionName, currentStepIndex, stepType, execCtx);
+        }
+        // Debug pause point - before executing step
+        if (this.debugController) {
+            const location = {
+                action: actionName,
+                stepIndex: currentStepIndex,
+                stepType,
+            };
+            if (this.debugController.shouldPause(location)) {
+                const snapshot = this.captureDebugSnapshot(actionName, currentStepIndex, stepType, { type: 'step' }, execCtx);
+                const command = await this.debugController.pause(snapshot);
+                this.handleDebugCommand(command);
+            }
         }
         try {
             switch (step.type) {
                 case 'FetchStep':
-                    await this.executeFetch(step);
+                    await this.executeFetch(step, execCtx, stepId);
                     break;
                 case 'ForStep':
-                    await this.executeFor(step, actionName);
+                    await this.executeFor(step, actionName, execCtx);
                     break;
                 case 'MapStep':
-                    await this.executeMap(step);
+                    await this.executeMap(step, execCtx);
                     break;
                 case 'ValidateStep':
-                    await this.executeValidate(step);
+                    await this.executeValidate(step, execCtx);
                     break;
                 case 'StoreStep':
-                    await this.executeStore(step);
+                    await this.executeStore(step, execCtx, stepId);
                     break;
                 case 'MatchStep':
-                    await this.executeMatch(step, actionName);
+                    await this.executeMatch(step, actionName, execCtx);
                     break;
                 case 'LetStep':
-                    await this.executeLet(step);
+                    await this.executeLet(step, execCtx);
+                    break;
+                case 'ApplyStep':
+                    await this.executeApply(step, execCtx);
                     break;
                 case 'WebhookStep':
-                    await this.executeWebhook(step);
+                    await this.executeWebhook(step, execCtx);
+                    break;
+                case 'PauseStep':
+                    await this.executePause(step, actionName, currentStepIndex, execCtx);
                     break;
                 default:
                     throw new Error(`Unknown step type: ${step.type}`);
             }
+            const stepDuration = Date.now() - stepStartTime;
+            // Record trace snapshot after step
+            if (this.traceRecorder) {
+                await this.traceRecorder.recordAfterStep(actionName, currentStepIndex, stepType, execCtx, stepDuration);
+            }
+            // Emit step.complete event (success)
+            this.eventEmitter?.emit('step.complete', {
+                actionName,
+                stepIndex: currentStepIndex,
+                stepType,
+                success: true,
+            });
+            // Append step.completed to the durable execution log.
+            await this.logEvent({ type: 'step.completed', stepId, attempt: scope.attempt });
         }
         catch (error) {
             // Re-throw flow control signals without recording as errors
             if (error instanceof SkipSignal ||
                 error instanceof RetrySignal ||
                 error instanceof JumpSignal ||
-                error instanceof QueueSignal) {
+                error instanceof QueueSignal ||
+                error instanceof PauseSignal) {
+                // Emit step.complete for flow control (not an error)
+                this.eventEmitter?.emit('step.complete', {
+                    actionName,
+                    stepIndex: currentStepIndex,
+                    stepType,
+                    success: true, // Flow control is not a failure
+                });
                 throw error;
             }
+            // Emit step.complete event (failure)
+            this.eventEmitter?.emit('step.complete', {
+                actionName,
+                stepIndex: currentStepIndex,
+                stepType,
+                success: false,
+                error: error.message,
+            });
             // AbortError is a controlled abort, still record it
             this.errors.push({
                 action: actionName,
@@ -573,91 +945,424 @@ export class MissionExecutor {
             });
             throw error;
         }
-        finally {
-            // Restore original context
-            if (ctx) {
-                this.ctx = originalCtx;
-            }
-        }
     }
-    async executeFetch(step) {
+    async executeFetch(step, ctx, stepId) {
         const fetchHandler = new FetchHandler({
-            ctx: this.ctx,
-            oasSources: this.oasSources,
-            sourceConfigs: this.sourceConfigs,
+            ctx,
+            oasSources: this.sourceManager.getAllOASSources(),
+            sourceConfigs: this.sourceManager.getAllSourceConfigs(),
             syncStore: this.syncStore,
             missionName: this.missionName,
             executionId: this.executionState?.id,
             dryRun: this.config.dryRun,
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
+            // Durable mode: mutating fetches carry a stable Idempotency-Key.
+            idempotency: this.executionLog && this.logExecutionId && stepId
+                ? { executionId: this.logExecutionId, stepId }
+                : undefined,
+            // Resumable backfill: seed pagination from the log and record each page.
+            pagination: step.backfill && this.executionLog && this.logExecutionId && stepId
+                ? {
+                    resume: this.pageProgress.get(stepId),
+                    maxItemsPerRun: this.config.backfillMaxItemsPerRun,
+                    onPage: async (progress) => {
+                        await this.logEvent({
+                            type: 'page.completed',
+                            stepId,
+                            page: progress.page,
+                            cursor: progress.cursor,
+                            recordCount: progress.recordCount,
+                            done: progress.done,
+                        });
+                    },
+                }
+                : undefined,
         });
+        // Capture when the request began; used as the checkpoint fallback time so
+        // a sync without an explicit update field never advances past records
+        // written during the fetch.
+        const fetchStartedAt = new Date();
         const result = await fetchHandler.execute(step);
-        this.ctx.response = result.data;
-        // Update sync checkpoint after successful fetch
+        ctx.response = result.data;
+        // Defer the sync checkpoint until the fetched data is durably stored.
         if (result.checkpointKey && this.syncStore) {
-            await fetchHandler.recordCheckpoint(result.checkpointKey, step, result.data);
+            const key = result.checkpointKey;
+            const data = result.data;
+            this.scopeFor(ctx).pendingCheckpoints.push(async () => {
+                const syncedAt = await fetchHandler.recordCheckpoint(key, step, data, fetchStartedAt);
+                if (syncedAt) {
+                    await this.logEvent({
+                        type: 'checkpoint.advanced',
+                        key,
+                        syncedAt: syncedAt.toISOString(),
+                        recordCount: Array.isArray(data) ? data.length : undefined,
+                        mission: this.missionName,
+                    });
+                }
+            });
+        }
+    }
+    /**
+     * Per-action mutable scope (step counter + deferred checkpoints). Lazily
+     * created so a step run with the bare mission context still works; normally
+     * executeAction installs a fresh scope that nested scopes inherit.
+     */
+    scopeFor(ctx) {
+        if (!ctx.actionScope) {
+            ctx.actionScope = { stepIndex: 0, attempt: 0, pendingCheckpoints: [] };
         }
+        return ctx.actionScope;
     }
-    async executeFor(step, actionName) {
+    /**
+     * Append an event to the execution log. No-op (zero cost) when no log is
+     * configured. The executionId is supplied from this run's stable log id.
+     */
+    async logEvent(event) {
+        if (!this.executionLog || !this.logExecutionId)
+            return;
+        await this.executionLog.append({
+            ...event,
+            executionId: this.logExecutionId,
+        });
+    }
+    /** Flush deferred sync checkpoints (called after a successful store / action). */
+    async flushPendingCheckpoints(ctx) {
+        const scope = this.scopeFor(ctx);
+        const pending = scope.pendingCheckpoints;
+        scope.pendingCheckpoints = [];
+        for (const record of pending) {
+            await record();
+        }
+    }
+    async executeFor(step, actionName, ctx) {
         const handler = new ForHandler({
-            ctx: this.ctx,
+            ctx,
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
             executeStep: (s, a, c) => this.executeStep(s, a, c),
             actionName,
+            debugController: this.debugController,
+            captureDebugSnapshot: this.debugController
+                ? (action, stepIndex, stepType, pauseReason, ctx) => this.captureDebugSnapshot(action, stepIndex, stepType, pauseReason, ctx)
+                : undefined,
+            handleDebugCommand: this.debugController
+                ? (cmd) => this.handleDebugCommand(cmd)
+                : undefined,
+            checkPause: this.config.controlServer ? () => this.checkPause() : undefined,
+            handleQueue: (signal) => this.handleQueue(signal),
         });
         await handler.execute(step);
     }
-    async executeMap(step) {
+    async executeMap(step, ctx) {
         const handler = new MapHandler({
-            ctx: this.ctx,
+            ctx,
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
         });
         await handler.execute(step);
     }
-    async executeValidate(step) {
+    async executeValidate(step, ctx) {
         const handler = new ValidateHandler({
-            ctx: this.ctx,
+            ctx,
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
         });
         await handler.execute(step);
     }
-    async executeStore(step) {
+    async executeStore(step, ctx, stepId) {
+        // Dry runs use synthetic fetch data that has no real keys; persisting it
+        // would both write garbage and trip key validation. Skip the write but
+        // still advance checkpoints so the dry run exercises the sync path.
+        if (this.config.dryRun) {
+            this.log(`[dry run] skipping store to ${step.target}`);
+            await this.flushPendingCheckpoints(ctx);
+            return;
+        }
+        // Step-level effect identity (attempt-independent): a store effect already
+        // applied in the log — whether by a prior run we are resuming or an earlier
+        // action attempt — must not be re-applied. This is the exactly-once-on-replay
+        // guarantee for store writes.
+        //
+        // The identity is keyed on the *content* being written, not just the target.
+        // A resumable backfill re-runs the same step (same stepId) once per run, each
+        // run storing a different page; keying on target alone made every run after
+        // the first collide on one id and skip the write, silently dropping every
+        // page but the first. Hashing the resolved payload keeps re-storing the same
+        // data idempotent (the upsert is a no-op anyway) while a different page is a
+        // distinct effect that applies.
+        const discriminator = `${step.target}::${this.storeContentHash(step, ctx)}`;
+        const fx = stepId && this.logExecutionId
+            ? effectId(this.logExecutionId, stepId, 0, 'store', discriminator)
+            : undefined;
+        if (fx && this.appliedEffects.has(fx)) {
+            this.log(`Skipping already-applied store to ${step.target} (resume)`);
+            await this.flushPendingCheckpoints(ctx);
+            return;
+        }
         const handler = new StoreHandler({
-            ctx: this.ctx,
+            ctx,
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
         });
         await handler.execute(step);
+        // Record the effect as applied so replay/retry skips it.
+        if (fx) {
+            this.appliedEffects.add(fx);
+            await this.logEvent({
+                type: 'effect.applied',
+                stepId: stepId,
+                attempt: 0,
+                effectType: 'store',
+                effectId: fx,
+            });
+        }
+        // Data is now durably stored — safe to advance any pending sync checkpoint.
+        await this.flushPendingCheckpoints(ctx);
     }
-    async executeMatch(step, actionName) {
+    /**
+     * A stable hash of the payload a store step will write, used to make the
+     * store-effect identity content-aware. Resolving the source is a pure read of
+     * the context (the same value the handler stores); on any evaluation failure we
+     * fall back to a constant so behaviour matches the old target-only identity
+     * rather than throwing inside the dedup path.
+     */
+    /** Load a pause's checkpoint into the shape the pause step uses to resume. */
+    async loadResumingPause(pauseId) {
+        const resumed = await this.pauseStore?.load(pauseId);
+        return resumed
+            ? { pauseId, checkpoint: resumed.checkpoint, payload: resumed.webhookPayload }
+            : undefined;
+    }
+    storeContentHash(step, ctx) {
+        try {
+            const source = evaluate(step.source, ctx);
+            return createHash('sha1')
+                .update(JSON.stringify(source) ?? 'null')
+                .digest('hex');
+        }
+        catch {
+            return 'unhashable';
+        }
+    }
+    async executeMatch(step, actionName, ctx) {
         const handler = new MatchHandler({
-            ctx: this.ctx,
+            ctx,
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
             executeStep: (s, a, c) => this.executeStep(s, a, c),
             actionName,
+            debugController: this.debugController,
+            captureDebugSnapshot: this.debugController
+                ? (action, stepIndex, stepType, pauseReason, execCtx) => this.captureDebugSnapshot(action, stepIndex, stepType, pauseReason, execCtx)
+                : undefined,
+            handleDebugCommand: this.debugController
+                ? (cmd) => this.handleDebugCommand(cmd)
+                : undefined,
         });
         await handler.execute(step);
         // Flow control signals (SkipSignal, RetrySignal, etc.) will propagate up
     }
-    async executeLet(step) {
-        const value = evaluate(step.value, this.ctx);
-        setVariable(this.ctx, step.name, value);
-        this.log(`Set variable '${step.name}' = ${JSON.stringify(value)}`);
+    async executeLet(step, ctx) {
+        const value = evaluate(step.value, ctx);
+        setVariable(ctx, step.name, value);
+        // Redact before logging: the value (or a nested field) may be a secret.
+        this.log(`Set variable '${step.name}' = ${JSON.stringify(redactNamedValue(step.name, value))}`);
+    }
+    async executeApply(step, ctx) {
+        const transform = this.transforms.get(step.transform);
+        if (!transform) {
+            throw new Error(`Transform '${step.transform}' not found`);
+        }
+        const handler = new ApplyHandler({
+            ctx,
+            log: (msg) => this.log(msg),
+            transform,
+        });
+        await handler.execute(step);
     }
-    async executeWebhook(step) {
+    async executeWebhook(step, ctx) {
         if (!this.config.webhookServer) {
             throw new Error('Webhook server not configured. Use --webhook flag or configure webhookServer in executor config.');
         }
         const handler = new WebhookHandler({
-            ctx: this.ctx,
+            ctx,
             webhookServer: this.config.webhookServer,
             executionId: this.executionState?.id ?? 'ephemeral',
             log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
         });
         await handler.execute(step);
     }
+    async executePause(step, actionName, stepIndex, ctx) {
+        if (!this.pauseManager) {
+            throw new Error('Pause manager not configured');
+        }
+        // Resuming this very pause: don't pause again. Restore the captured
+        // checkpoint (variables + response, plus any webhook payload) and fall
+        // through so the steps after the pause run to completion.
+        const resuming = this.resumingPause;
+        if (resuming &&
+            resuming.checkpoint.action === actionName &&
+            resuming.checkpoint.stepIndex === stepIndex + 1) {
+            this.resumingPause = undefined;
+            for (const [key, value] of Object.entries(resuming.checkpoint.variables ?? {})) {
+                ctx.variables.set(key, value);
+            }
+            ctx.response = resuming.payload ?? resuming.checkpoint.response;
+            this.log(`Resuming past pause ${resuming.pauseId}`);
+            return;
+        }
+        // Mark execution state as paused before creating pause
+        if (this.executionState) {
+            this.executionState.status = 'paused';
+            await this.saveExecutionState();
+        }
+        const handler = new PauseHandler({
+            ctx,
+            log: (msg) => this.log(msg),
+            emit: this.eventEmitter
+                ? (type, payload) => this.eventEmitter.emit(type, payload)
+                : undefined,
+            pauseManager: this.pauseManager,
+            // Anchor the pause to the durable log id so its pause.created lands under
+            // the same execution the log replays on resume (executionState may be
+            // absent when running without an execution store).
+            executionId: this.logExecutionId ?? this.executionState?.id ?? 'ephemeral',
+            mission: this.missionName ?? 'unknown',
+            actionName,
+            stageIndex: this.currentStageIndex,
+            stepIndex,
+        });
+        // This will throw PauseSignal
+        await handler.execute(step);
+    }
     log(message) {
-        if (this.config.verbose) {
+        if (this.logger) {
+            this.logger.info(message);
+        }
+        else if (this.config.verbose) {
             console.log(`[Reqon] ${message}`);
         }
     }
+    /**
+     * Check if pause has been requested and handle it
+     * Should be called at safe pause points (between stages, loop iterations)
+     */
+    async checkPause() {
+        if (!this.config.controlServer?.isPauseRequested()) {
+            return;
+        }
+        this.log('Pause requested - saving state and pausing execution');
+        // Save state as paused
+        if (this.executionState) {
+            this.executionState.status = 'paused';
+            await this.saveExecutionState();
+        }
+        // Clear the pause request (it's been handled)
+        this.config.controlServer.clearPauseRequest();
+        // Throw pause signal to stop execution
+        throw new PauseSignal();
+    }
+    /**
+     * Update control server with current state
+     */
+    updateControlServerState() {
+        if (this.config.controlServer && this.executionState) {
+            this.config.controlServer.updateState(this.executionState);
+        }
+    }
+    getStepType(stepType) {
+        const mapping = {
+            FetchStep: 'fetch',
+            ForStep: 'for',
+            MapStep: 'map',
+            ValidateStep: 'validate',
+            StoreStep: 'store',
+            MatchStep: 'match',
+            LetStep: 'let',
+            WebhookStep: 'webhook',
+            PauseStep: 'pause',
+        };
+        return mapping[stepType] ?? 'fetch';
+    }
+    /** Get the event emitter (for external access) */
+    getEventEmitter() {
+        return this.eventEmitter;
+    }
+    /** Get the structured logger (for external access) */
+    getLogger() {
+        return this.logger;
+    }
+    /** Get the debug controller (for external access) */
+    getDebugController() {
+        return this.debugController;
+    }
+    /** Capture current execution state for debugging */
+    captureDebugSnapshot(action, stepIndex, stepType, pauseReason, ctx) {
+        // Collect variables from context chain
+        const variables = {};
+        let current = ctx;
+        while (current) {
+            for (const [key, value] of current.variables) {
+                if (!(key in variables)) {
+                    variables[key] = value;
+                }
+            }
+            current = current.parent;
+        }
+        // Collect store info
+        const stores = {};
+        for (const [name, _store] of ctx.stores) {
+            stores[name] = {
+                type: ctx.storeTypes.get(name) ?? 'unknown',
+                count: -1, // Would need async call to get count
+            };
+        }
+        return {
+            mission: this.missionName ?? 'unknown',
+            action,
+            stepIndex,
+            stepType,
+            pauseReason,
+            variables,
+            stores,
+            response: ctx.response,
+        };
+    }
+    /** Handle debug command and update state */
+    handleDebugCommand(cmd) {
+        if (!this.debugController)
+            return;
+        switch (cmd.type) {
+            case 'abort':
+                throw new AbortError('Execution aborted by debugger');
+            case 'continue':
+                this.debugController.mode = 'run';
+                break;
+            case 'step':
+                this.debugController.mode = 'step';
+                break;
+            case 'step-into':
+                this.debugController.mode = 'step-into';
+                break;
+            case 'step-over':
+                this.debugController.mode = 'step-over';
+                break;
+        }
+    }
 }