reqon-dsl 0.2.0 → 0.4.0

package/dist/trace/recorder.js

@@ -0,0 +1,157 @@
+/**
+ * Trace Recorder - Captures execution state for time-travel debugging
+ *
+ * Used by the executor to record snapshots at each step,
+ * building a complete trace that can be replayed later.
+ */
+import { createExecutionTrace, generateSnapshotId, safeClone, truncateForTrace, } from './state.js';
+import { redactSecrets } from '../utils/redact.js';
+/**
+ * Records execution state for time-travel debugging
+ */
+export class TraceRecorder {
+    config;
+    trace;
+    snapshotIndex = 0;
+    currentLoopContext;
+    constructor(config) {
+        this.config = config;
+        this.trace = createExecutionTrace(config.executionId, config.mission, config.mode, config.metadata);
+    }
+    /**
+     * Record a snapshot before step execution
+     */
+    async recordBeforeStep(action, stepIndex, stepType, ctx) {
+        const snapshot = this.createSnapshot(action, stepIndex, stepType, 'before', ctx);
+        await this.addSnapshot(snapshot);
+    }
+    /**
+     * Record a snapshot after step execution
+     */
+    async recordAfterStep(action, stepIndex, stepType, ctx, stepDuration, error) {
+        const snapshot = this.createSnapshot(action, stepIndex, stepType, 'after', ctx);
+        snapshot.stepDuration = stepDuration;
+        snapshot.error = error;
+        await this.addSnapshot(snapshot);
+    }
+    /**
+     * Set loop context for subsequent snapshots
+     */
+    setLoopContext(context) {
+        this.currentLoopContext = context;
+    }
+    /**
+     * Finalize the trace (called when execution completes)
+     */
+    async finalize(success) {
+        this.trace.completedAt = new Date();
+        this.trace.duration = this.trace.completedAt.getTime() - this.trace.startedAt.getTime();
+        this.trace.success = success;
+        // If not streaming, save entire trace at end
+        if (!this.config.streaming) {
+            await this.config.store.save(this.trace);
+        }
+        return this.trace;
+    }
+    /**
+     * Get the current trace (without finalizing)
+     */
+    getTrace() {
+        return this.trace;
+    }
+    /**
+     * Get a specific snapshot by index
+     */
+    getSnapshot(index) {
+        return this.trace.snapshots[index];
+    }
+    /**
+     * Get the total number of snapshots recorded. In streaming mode the in-memory
+     * array is bounded (older snapshots live only on disk), so this reflects the
+     * true total rather than the retained window.
+     */
+    getSnapshotCount() {
+        return this.snapshotIndex;
+    }
+    createSnapshot(action, stepIndex, stepType, phase, ctx) {
+        const index = this.snapshotIndex++;
+        // Capture variables from context chain. Trace files are diagnostic and
+        // persisted to disk, so redact credential-looking fields.
+        const variables = redactSecrets(this.captureVariables(ctx));
+        // Capture store states
+        const stores = this.captureStores(ctx);
+        // Capture response (truncated for large responses)
+        const response = this.config.mode === 'full'
+            ? redactSecrets(truncateForTrace(safeClone(ctx.response)))
+            : undefined;
+        return {
+            id: generateSnapshotId(this.trace.id, index),
+            index,
+            timestamp: new Date(),
+            mission: this.trace.mission,
+            action,
+            stepIndex,
+            stepType,
+            phase,
+            variables,
+            response,
+            stores,
+            loopContext: this.currentLoopContext ? { ...this.currentLoopContext } : undefined,
+        };
+    }
+    captureVariables(ctx) {
+        const variables = {};
+        let current = ctx;
+        while (current) {
+            for (const [key, value] of current.variables) {
+                if (!(key in variables)) {
+                    // Clone and truncate for trace storage
+                    variables[key] =
+                        this.config.mode === 'full' ? truncateForTrace(safeClone(value)) : typeof value;
+                }
+            }
+            current = current.parent;
+        }
+        return variables;
+    }
+    captureStores(ctx) {
+        const stores = {};
+        const maxItems = this.config.maxStoreItems ?? 10;
+        for (const [name, _store] of ctx.stores) {
+            const storeType = ctx.storeTypes.get(name) ?? 'unknown';
+            // Note: Getting actual item count would require async call
+            // For now, we just record the type
+            stores[name] = {
+                type: storeType,
+                itemCount: -1, // Would need async to get actual count
+                sampleItems: this.config.mode === 'full' ? [] : undefined,
+            };
+            // In full mode, we could sample items if we had sync access
+            // For now, this is a placeholder for future enhancement
+            if (this.config.mode === 'full' && maxItems > 0) {
+                // TODO: Add async store sampling if needed
+            }
+        }
+        return stores;
+    }
+    /** Cap on snapshots kept in memory while streaming (each is already on disk). */
+    static MAX_STREAMED_IN_MEMORY = 200;
+    async addSnapshot(snapshot) {
+        this.trace.snapshots.push(snapshot);
+        if (this.config.streaming) {
+            // Persisted immediately, so the in-memory copy is only a recent window for
+            // live inspection — bound it so a long run doesn't grow without limit.
+            await this.config.store.appendSnapshot(this.trace.id, snapshot);
+            const cap = TraceRecorder.MAX_STREAMED_IN_MEMORY;
+            if (this.trace.snapshots.length > cap) {
+                this.trace.snapshots.splice(0, this.trace.snapshots.length - cap);
+            }
+        }
+    }
+}
+/**
+ * Create a trace recorder for an execution
+ */
+export function createTraceRecorder(config) {
+    return new TraceRecorder(config);
+}

package/dist/trace/replay.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Trace Replay - Time-travel debugging for execution traces
+ *
+ * Allows stepping through recorded execution traces,
+ * inspecting state at each point, and comparing across runs.
+ */
+import type { TraceStore } from './store.js';
+import type { ExecutionTrace, TraceSnapshot, LoopContext } from './state.js';
+/**
+ * Replay session state
+ */
+export interface ReplaySession {
+    /** Trace being replayed */
+    trace: ExecutionTrace;
+    /** Current snapshot index */
+    currentIndex: number;
+    /** Total snapshots */
+    totalSnapshots: number;
+    /** Current snapshot */
+    currentSnapshot: TraceSnapshot | null;
+    /** Replay mode */
+    mode: 'paused' | 'stepping' | 'running';
+}
+/**
+ * Replay step result
+ */
+export interface ReplayStepResult {
+    /** The snapshot at this step */
+    snapshot: TraceSnapshot;
+    /** Whether there are more steps */
+    hasNext: boolean;
+    /** Whether there are previous steps */
+    hasPrevious: boolean;
+    /** Human-readable summary of this step */
+    summary: string;
+}
+/**
+ * Replay controller for navigating execution traces
+ */
+export declare class TraceReplayer {
+    private store;
+    private session;
+    constructor(store: TraceStore);
+    /**
+     * Load a trace and start a replay session
+     */
+    loadTrace(traceId: string): Promise<ReplaySession>;
+    /**
+     * Load the latest trace for a mission
+     */
+    loadLatest(mission: string): Promise<ReplaySession>;
+    /**
+     * Get current session state
+     */
+    getSession(): ReplaySession | null;
+    /**
+     * Go to a specific step by index
+     */
+    goToStep(index: number): Promise<ReplayStepResult>;
+    /**
+     * Go to the next step
+     */
+    next(): Promise<ReplayStepResult | null>;
+    /**
+     * Go to the previous step
+     */
+    previous(): Promise<ReplayStepResult | null>;
+    /**
+     * Jump to the first step of an action
+     */
+    goToAction(actionName: string): Promise<ReplayStepResult | null>;
+    /**
+     * Jump to a step where a specific variable changed
+     */
+    findVariableChange(variableName: string, fromIndex?: number): Promise<ReplayStepResult | null>;
+    /**
+     * Find steps where an error occurred
+     */
+    findErrors(): number[];
+    /**
+     * Get all unique action names in the trace
+     */
+    getActions(): string[];
+    /**
+     * Get execution timeline with key events
+     */
+    getTimeline(): TimelineEvent[];
+    /**
+     * Compare two snapshots
+     */
+    compareSnapshots(index1: number, index2: number): SnapshotDiff;
+    /**
+     * Export trace to JSON for external analysis
+     */
+    exportTrace(): ExecutionTrace | null;
+    private formatStepResult;
+}
+/**
+ * Timeline event types
+ */
+export interface TimelineEvent {
+    type: 'action-start' | 'error' | 'loop-iteration' | 'checkpoint';
+    index: number;
+    action: string;
+    step?: string;
+    message?: string;
+    loopContext?: LoopContext;
+    timestamp: Date;
+}
+/**
+ * Variable change in diff
+ */
+export interface VariableChange {
+    name: string;
+    before: unknown;
+    after: unknown;
+    type: 'added' | 'removed' | 'changed';
+}
+/**
+ * Snapshot comparison result
+ */
+export interface SnapshotDiff {
+    snapshot1: TraceSnapshot;
+    snapshot2: TraceSnapshot;
+    variableChanges: VariableChange[];
+    responseDifferent: boolean;
+    stepsExecuted: number;
+}
+/**
+ * Create a trace replayer
+ */
+export declare function createTraceReplayer(store: TraceStore): TraceReplayer;

package/dist/trace/replay.js

@@ -0,0 +1,264 @@
+/**
+ * Trace Replay - Time-travel debugging for execution traces
+ *
+ * Allows stepping through recorded execution traces,
+ * inspecting state at each point, and comparing across runs.
+ */
+/**
+ * Replay controller for navigating execution traces
+ */
+export class TraceReplayer {
+    store;
+    session = null;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Load a trace and start a replay session
+     */
+    async loadTrace(traceId) {
+        const trace = await this.store.load(traceId);
+        if (!trace) {
+            throw new Error(`Trace not found: ${traceId}`);
+        }
+        this.session = {
+            trace,
+            currentIndex: 0,
+            totalSnapshots: trace.snapshots.length,
+            currentSnapshot: trace.snapshots[0] ?? null,
+            mode: 'paused',
+        };
+        return this.session;
+    }
+    /**
+     * Load the latest trace for a mission
+     */
+    async loadLatest(mission) {
+        const trace = await this.store.findLatest(mission);
+        if (!trace) {
+            throw new Error(`No traces found for mission: ${mission}`);
+        }
+        // Load full trace with snapshots
+        const fullTrace = await this.store.load(trace.id);
+        if (!fullTrace) {
+            throw new Error(`Failed to load trace: ${trace.id}`);
+        }
+        this.session = {
+            trace: fullTrace,
+            currentIndex: 0,
+            totalSnapshots: fullTrace.snapshots.length,
+            currentSnapshot: fullTrace.snapshots[0] ?? null,
+            mode: 'paused',
+        };
+        return this.session;
+    }
+    /**
+     * Get current session state
+     */
+    getSession() {
+        return this.session;
+    }
+    /**
+     * Go to a specific step by index
+     */
+    async goToStep(index) {
+        if (!this.session) {
+            throw new Error('No replay session active');
+        }
+        if (index < 0 || index >= this.session.totalSnapshots) {
+            throw new Error(`Invalid step index: ${index}. Valid range: 0-${this.session.totalSnapshots - 1}`);
+        }
+        this.session.currentIndex = index;
+        this.session.currentSnapshot = this.session.trace.snapshots[index];
+        return this.formatStepResult(this.session.currentSnapshot);
+    }
+    /**
+     * Go to the next step
+     */
+    async next() {
+        if (!this.session) {
+            throw new Error('No replay session active');
+        }
+        if (this.session.currentIndex >= this.session.totalSnapshots - 1) {
+            return null;
+        }
+        return this.goToStep(this.session.currentIndex + 1);
+    }
+    /**
+     * Go to the previous step
+     */
+    async previous() {
+        if (!this.session) {
+            throw new Error('No replay session active');
+        }
+        if (this.session.currentIndex <= 0) {
+            return null;
+        }
+        return this.goToStep(this.session.currentIndex - 1);
+    }
+    /**
+     * Jump to the first step of an action
+     */
+    async goToAction(actionName) {
+        if (!this.session) {
+            throw new Error('No replay session active');
+        }
+        const index = this.session.trace.snapshots.findIndex((s) => s.action === actionName && s.phase === 'before');
+        if (index === -1) {
+            return null;
+        }
+        return this.goToStep(index);
+    }
+    /**
+     * Jump to a step where a specific variable changed
+     */
+    async findVariableChange(variableName, fromIndex = 0) {
+        if (!this.session) {
+            throw new Error('No replay session active');
+        }
+        let previousValue = undefined;
+        for (let i = fromIndex; i < this.session.totalSnapshots; i++) {
+            const snapshot = this.session.trace.snapshots[i];
+            const currentValue = snapshot.variables[variableName];
+            if (i === fromIndex) {
+                previousValue = currentValue;
+                continue;
+            }
+            if (JSON.stringify(currentValue) !== JSON.stringify(previousValue)) {
+                return this.goToStep(i);
+            }
+            previousValue = currentValue;
+        }
+        return null;
+    }
+    /**
+     * Find steps where an error occurred
+     */
+    findErrors() {
+        if (!this.session) {
+            return [];
+        }
+        return this.session.trace.snapshots.map((s, i) => (s.error ? i : -1)).filter((i) => i !== -1);
+    }
+    /**
+     * Get all unique action names in the trace
+     */
+    getActions() {
+        if (!this.session) {
+            return [];
+        }
+        const actions = new Set();
+        for (const snapshot of this.session.trace.snapshots) {
+            actions.add(snapshot.action);
+        }
+        return Array.from(actions);
+    }
+    /**
+     * Get execution timeline with key events
+     */
+    getTimeline() {
+        if (!this.session) {
+            return [];
+        }
+        const events = [];
+        let currentAction = '';
+        for (const snapshot of this.session.trace.snapshots) {
+            if (snapshot.action !== currentAction && snapshot.phase === 'before') {
+                events.push({
+                    type: 'action-start',
+                    index: snapshot.index,
+                    action: snapshot.action,
+                    timestamp: snapshot.timestamp,
+                });
+                currentAction = snapshot.action;
+            }
+            if (snapshot.error) {
+                events.push({
+                    type: 'error',
+                    index: snapshot.index,
+                    action: snapshot.action,
+                    step: snapshot.stepType,
+                    message: snapshot.error,
+                    timestamp: snapshot.timestamp,
+                });
+            }
+            if (snapshot.loopContext && snapshot.phase === 'before') {
+                events.push({
+                    type: 'loop-iteration',
+                    index: snapshot.index,
+                    action: snapshot.action,
+                    loopContext: snapshot.loopContext,
+                    timestamp: snapshot.timestamp,
+                });
+            }
+        }
+        return events;
+    }
+    /**
+     * Compare two snapshots
+     */
+    compareSnapshots(index1, index2) {
+        if (!this.session) {
+            throw new Error('No replay session active');
+        }
+        const snap1 = this.session.trace.snapshots[index1];
+        const snap2 = this.session.trace.snapshots[index2];
+        if (!snap1 || !snap2) {
+            throw new Error('Invalid snapshot indices');
+        }
+        const variableChanges = [];
+        // Find variables that changed
+        const allVars = new Set([...Object.keys(snap1.variables), ...Object.keys(snap2.variables)]);
+        for (const varName of allVars) {
+            const val1 = snap1.variables[varName];
+            const val2 = snap2.variables[varName];
+            if (JSON.stringify(val1) !== JSON.stringify(val2)) {
+                variableChanges.push({
+                    name: varName,
+                    before: val1,
+                    after: val2,
+                    type: val1 === undefined ? 'added' : val2 === undefined ? 'removed' : 'changed',
+                });
+            }
+        }
+        return {
+            snapshot1: snap1,
+            snapshot2: snap2,
+            variableChanges,
+            responseDifferent: JSON.stringify(snap1.response) !== JSON.stringify(snap2.response),
+            stepsExecuted: index2 - index1,
+        };
+    }
+    /**
+     * Export trace to JSON for external analysis
+     */
+    exportTrace() {
+        return this.session?.trace ?? null;
+    }
+    formatStepResult(snapshot) {
+        const hasNext = this.session.currentIndex < this.session.totalSnapshots - 1;
+        const hasPrevious = this.session.currentIndex > 0;
+        let summary = `[${snapshot.index}] ${snapshot.phase.toUpperCase()} ${snapshot.action}.${snapshot.stepType}`;
+        if (snapshot.loopContext) {
+            summary += ` (loop ${snapshot.loopContext.itemIndex + 1}/${snapshot.loopContext.totalItems})`;
+        }
+        if (snapshot.stepDuration !== undefined) {
+            summary += ` - ${snapshot.stepDuration}ms`;
+        }
+        if (snapshot.error) {
+            summary += ` - ERROR: ${snapshot.error}`;
+        }
+        return {
+            snapshot,
+            hasNext,
+            hasPrevious,
+            summary,
+        };
+    }
+}
+/**
+ * Create a trace replayer
+ */
+export function createTraceReplayer(store) {
+    return new TraceReplayer(store);
+}

package/dist/trace/state.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Trace State - Types for time-travel debugging
+ *
+ * Captures full execution state snapshots at each step,
+ * enabling replay and debugging of pipeline runs.
+ */
+/**
+ * A single step snapshot in the execution trace
+ */
+export interface TraceSnapshot {
+    /** Unique snapshot ID */
+    id: string;
+    /** Index in the trace sequence */
+    index: number;
+    /** Timestamp when snapshot was captured */
+    timestamp: Date;
+    /** Mission name */
+    mission: string;
+    /** Current action name */
+    action: string;
+    /** Step index within action */
+    stepIndex: number;
+    /** Step type (fetch, for, map, etc.) */
+    stepType: string;
+    /** Phase: before or after step execution */
+    phase: 'before' | 'after';
+    /** All variables in scope (deep cloned) */
+    variables: Record<string, unknown>;
+    /** Current response value (deep cloned) */
+    response?: unknown;
+    /** Store states - map of store name to item count and sample */
+    stores: Record<string, StoreSnapshot>;
+    /** Duration of step execution (only for 'after' phase) */
+    stepDuration?: number;
+    /** Error if step failed */
+    error?: string;
+    /** For loop context (if inside a for loop) */
+    loopContext?: LoopContext;
+}
+/**
+ * Snapshot of a store's state
+ */
+export interface StoreSnapshot {
+    /** Store type (memory, file, etc.) */
+    type: string;
+    /** Number of items in store */
+    itemCount: number;
+    /** Sample of recent items (limited to avoid huge traces) */
+    sampleItems?: unknown[];
+}
+/**
+ * Context when inside a for loop
+ */
+export interface LoopContext {
+    /** Loop variable name */
+    variable: string;
+    /** Current item index */
+    itemIndex: number;
+    /** Total items in collection */
+    totalItems: number;
+    /** Current item value */
+    currentItem?: unknown;
+}
+/**
+ * Complete trace for a mission execution
+ */
+export interface ExecutionTrace {
+    /** Trace ID (same as execution ID) */
+    id: string;
+    /** Mission name */
+    mission: string;
+    /** Trace mode (full or minimal) */
+    mode: 'full' | 'minimal';
+    /** When trace started */
+    startedAt: Date;
+    /** When trace completed */
+    completedAt?: Date;
+    /** Total duration in ms */
+    duration?: number;
+    /** Whether execution succeeded */
+    success?: boolean;
+    /** All snapshots in execution order */
+    snapshots: TraceSnapshot[];
+    /** Metadata from execution */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Generate a unique snapshot ID
+ */
+export declare function generateSnapshotId(traceId: string, index: number): string;
+/**
+ * Create a new execution trace
+ */
+export declare function createExecutionTrace(executionId: string, mission: string, mode: 'full' | 'minimal', metadata?: Record<string, unknown>): ExecutionTrace;
+/**
+ * Safe deep clone that handles circular references and special types
+ */
+export declare function safeClone<T>(value: T, maxDepth?: number): T;
+/**
+ * Truncate large values for trace storage
+ */
+export declare function truncateForTrace(value: unknown, maxItems?: number, maxStringLength?: number): unknown;