reqon-dsl 0.2.0 → 0.3.0

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;

package/dist/trace/state.js

@@ -0,0 +1,86 @@
+/**
+ * Trace State - Types for time-travel debugging
+ *
+ * Captures full execution state snapshots at each step,
+ * enabling replay and debugging of pipeline runs.
+ */
+/**
+ * Generate a unique snapshot ID
+ */
+export function generateSnapshotId(traceId, index) {
+    return `${traceId}_snap_${index.toString().padStart(6, '0')}`;
+}
+/**
+ * Create a new execution trace
+ */
+export function createExecutionTrace(executionId, mission, mode, metadata) {
+    return {
+        id: executionId,
+        mission,
+        mode,
+        startedAt: new Date(),
+        snapshots: [],
+        metadata,
+    };
+}
+/**
+ * Safe deep clone that handles circular references and special types
+ */
+export function safeClone(value, maxDepth = 10) {
+    const seen = new WeakSet();
+    function clone(val, depth) {
+        if (depth > maxDepth)
+            return '[max depth exceeded]';
+        if (val === null || typeof val !== 'object')
+            return val;
+        if (val instanceof Date)
+            return new Date(val.getTime());
+        if (val instanceof RegExp)
+            return new RegExp(val.source, val.flags);
+        if (seen.has(val))
+            return '[circular reference]';
+        seen.add(val);
+        if (Array.isArray(val)) {
+            return val.map((item) => clone(item, depth + 1));
+        }
+        if (val instanceof Map) {
+            const result = {};
+            for (const [k, v] of val) {
+                result[String(k)] = clone(v, depth + 1);
+            }
+            return result;
+        }
+        if (val instanceof Set) {
+            return Array.from(val).map((item) => clone(item, depth + 1));
+        }
+        const result = {};
+        for (const key of Object.keys(val)) {
+            result[key] = clone(val[key], depth + 1);
+        }
+        return result;
+    }
+    return clone(value, 0);
+}
+/**
+ * Truncate large values for trace storage
+ */
+export function truncateForTrace(value, maxItems = 100, maxStringLength = 1000) {
+    if (typeof value === 'string' && value.length > maxStringLength) {
+        return value.slice(0, maxStringLength) + `... [truncated, ${value.length} chars total]`;
+    }
+    if (Array.isArray(value) && value.length > maxItems) {
+        return [...value.slice(0, maxItems), `... [truncated, ${value.length} items total]`];
+    }
+    if (value && typeof value === 'object') {
+        const keys = Object.keys(value);
+        if (keys.length > maxItems) {
+            const result = {};
+            for (const key of keys.slice(0, maxItems)) {
+                result[key] = value[key];
+            }
+            result['__truncated__'] = `${keys.length} keys total`;
+            return result;
+        }
+    }
+    return value;
+}

package/dist/trace/store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Trace Store - Persistence for execution traces
+ *
+ * Stores complete execution traces for time-travel debugging,
+ * enabling replay and step-by-step inspection of past runs.
+ */
+import type { ExecutionTrace, TraceSnapshot } from './state.js';
+/**
+ * Trace store interface
+ */
+export interface TraceStore {
+    /** Save a complete trace */
+    save(trace: ExecutionTrace): Promise<void>;
+    /** Append a snapshot to an existing trace */
+    appendSnapshot(traceId: string, snapshot: TraceSnapshot): Promise<void>;
+    /** Load a trace by ID */
+    load(id: string): Promise<ExecutionTrace | null>;
+    /** Load a specific snapshot from a trace */
+    loadSnapshot(traceId: string, snapshotIndex: number): Promise<TraceSnapshot | null>;
+    /** List all traces for a mission */
+    listByMission(mission: string, limit?: number): Promise<ExecutionTrace[]>;
+    /** List recent traces across all missions */
+    listRecent(limit?: number): Promise<ExecutionTrace[]>;
+    /** Delete a trace */
+    delete(id: string): Promise<void>;
+    /** Find the latest trace for a mission */
+    findLatest(mission: string): Promise<ExecutionTrace | null>;
+    /** Get trace metadata without loading all snapshots (for performance) */
+    getMetadata(id: string): Promise<Omit<ExecutionTrace, 'snapshots'> | null>;
+}
+/**
+ * File-based trace store
+ * Stores traces in .reqon-data/traces/ with separate files for metadata and snapshots
+ */
+export declare class FileTraceStore implements TraceStore {
+    private baseDir;
+    private initialized;
+    constructor(baseDir?: string);
+    private getTraceDir;
+    private getMetadataPath;
+    private getSnapshotPath;
+    private deserializeTrace;
+    private deserializeSnapshot;
+    save(trace: ExecutionTrace): Promise<void>;
+    appendSnapshot(traceId: string, snapshot: TraceSnapshot): Promise<void>;
+    load(id: string): Promise<ExecutionTrace | null>;
+    loadSnapshot(traceId: string, snapshotIndex: number): Promise<TraceSnapshot | null>;
+    listByMission(mission: string, limit?: number): Promise<ExecutionTrace[]>;
+    listRecent(limit?: number): Promise<ExecutionTrace[]>;
+    delete(id: string): Promise<void>;
+    findLatest(mission: string): Promise<ExecutionTrace | null>;
+    getMetadata(id: string): Promise<Omit<ExecutionTrace, 'snapshots'> | null>;
+}
+/**
+ * In-memory trace store (for testing)
+ */
+export declare class MemoryTraceStore implements TraceStore {
+    private traces;
+    save(trace: ExecutionTrace): Promise<void>;
+    appendSnapshot(traceId: string, snapshot: TraceSnapshot): Promise<void>;
+    load(id: string): Promise<ExecutionTrace | null>;
+    loadSnapshot(traceId: string, snapshotIndex: number): Promise<TraceSnapshot | null>;
+    listByMission(mission: string, limit?: number): Promise<ExecutionTrace[]>;
+    listRecent(limit?: number): Promise<ExecutionTrace[]>;
+    delete(id: string): Promise<void>;
+    findLatest(mission: string): Promise<ExecutionTrace | null>;
+    getMetadata(id: string): Promise<Omit<ExecutionTrace, 'snapshots'> | null>;
+    clear(): void;
+}