reqon-dsl 0.2.0 → 0.3.0

package/dist/plugin.js

@@ -1,18 +1,15 @@
 /**
- * Reqon plugin for Vague.
- *
- * This plugin registers Reqon's keywords and statement parsers with Vague,
- * allowing Vague to parse Reqon syntax when the plugin is registered.
- *
- * Usage:
- *   import { registerPlugin } from 'vague-lang';
- *   import { reqonPlugin } from 'reqon';
- *   registerPlugin(reqonPlugin);
- *
- * Or simply import the plugin module to auto-register:
- *   import 'reqon/plugin';
+ * ---
+ * purpose: Vague plugin - registers Reqon keywords with Vague's lexer
+ * exports:
+ *   - reqonPlugin - plugin object for manual registration
+ *   - registerReqonPlugin, unregisterReqonPlugin - registration helpers
+ * related:
+ *   - ./lexer/tokens.ts - REQON_KEYWORDS map
+ *   - vague-lang - parent DSL framework
+ * ---
  */
-import { registerPlugin, unregisterPlugin, } from 'vague-lang';
+import { registerPlugin, unregisterPlugin } from 'vague-lang';
 import { REQON_KEYWORDS } from './lexer/tokens.js';
 /**
  * Convert REQON_KEYWORDS map to PluginKeyword array for Vague plugin system.

package/dist/stores/factory.d.ts

@@ -33,4 +33,4 @@ export declare function createStore(options: CreateStoreOptions): StoreAdapter;
  * Map DSL store type to adapter type
  * In development mode, sql/nosql fall back to file stores
  */
-export declare function resolveStoreType(dslType: 'sql' | 'nosql' | 'memory', developmentMode?: boolean): StoreType;
+export declare function resolveStoreType(dslType: 'sql' | 'nosql' | 'memory' | 'file' | 'postgrest', developmentMode?: boolean): StoreType;

package/dist/stores/factory.js

@@ -61,8 +61,9 @@ export function createStore(options) {
  * In development mode, sql/nosql fall back to file stores
  */
 export function resolveStoreType(dslType, developmentMode = true) {
-    if (dslType === 'memory') {
-        return 'memory';
+    // These types are used directly
+    if (dslType === 'memory' || dslType === 'file' || dslType === 'postgrest') {
+        return dslType;
     }
     if (developmentMode) {
         // Use file stores for local development

package/dist/stores/file.d.ts

@@ -12,6 +12,9 @@ export interface FileStoreOptions {
 /**
  * File-based JSON store for local development
  * Persists data to .reqon-data/{name}.json
+ *
+ * Use FileStore.create() for async initialization (recommended),
+ * or new FileStore() for lazy initialization (backward compatible).
  */
 export declare class FileStore implements StoreAdapter {
     private data;
@@ -19,9 +22,28 @@ export declare class FileStore implements StoreAdapter {
     private options;
     private dirty;
     private initialized;
+    private initError;
     private debounceTimer;
     private pendingWrite;
+    /**
+     * Create a FileStore with async initialization (recommended).
+     * The store is fully initialized when the promise resolves.
+     *
+     * @example
+     * const store = await FileStore.create('my-store', { baseDir: '.data' });
+     */
+    static create(name: string, options?: FileStoreOptions): Promise<FileStore>;
+    /**
+     * Constructor for lazy initialization (backward compatible).
+     * Each operation will wait for initialization to complete.
+     * Prefer FileStore.create() for explicit async initialization.
+     */
     constructor(name: string, options?: FileStoreOptions);
+    /**
+     * Ensure the store is initialized. Safe to call multiple times.
+     * Throws if initialization previously failed.
+     */
+    private ensureInitialized;
     private init;
     private load;
     private persist;
@@ -35,6 +57,10 @@ export declare class FileStore implements StoreAdapter {
         key: string;
         value: Record<string, unknown>;
     }>): Promise<void>;
+    bulkUpsert(records: Array<{
+        key: string;
+        value: Record<string, unknown>;
+    }>): Promise<void>;
     update(key: string, value: Partial<Record<string, unknown>>): Promise<void>;
     delete(key: string): Promise<void>;
     list(filter?: StoreFilter): Promise<Record<string, unknown>[]>;

package/dist/stores/file.js

@@ -12,19 +12,58 @@ const DEFAULT_OPTIONS = {
 /**
  * File-based JSON store for local development
  * Persists data to .reqon-data/{name}.json
+ *
+ * Use FileStore.create() for async initialization (recommended),
+ * or new FileStore() for lazy initialization (backward compatible).
  */
 export class FileStore {
     data = new Map();
     filePath;
     options;
     dirty = false;
-    initialized;
+    initialized = null;
+    initError = null;
     debounceTimer = null;
     pendingWrite = null;
+    /**
+     * Create a FileStore with async initialization (recommended).
+     * The store is fully initialized when the promise resolves.
+     *
+     * @example
+     * const store = await FileStore.create('my-store', { baseDir: '.data' });
+     */
+    static async create(name, options = {}) {
+        const store = new FileStore(name, options);
+        await store.ensureInitialized();
+        return store;
+    }
+    /**
+     * Constructor for lazy initialization (backward compatible).
+     * Each operation will wait for initialization to complete.
+     * Prefer FileStore.create() for explicit async initialization.
+     */
     constructor(name, options = {}) {
         this.options = { ...DEFAULT_OPTIONS, ...options };
         this.filePath = join(this.options.baseDir, `${name}.json`);
-        this.initialized = this.init();
+        // Lazy initialization - init() is called on first operation
+    }
+    /**
+     * Ensure the store is initialized. Safe to call multiple times.
+     * Throws if initialization previously failed.
+     */
+    async ensureInitialized() {
+        // If init previously failed, throw the cached error
+        if (this.initError) {
+            throw this.initError;
+        }
+        // If not yet started, start initialization
+        if (this.initialized === null) {
+            this.initialized = this.init().catch((error) => {
+                this.initError = error instanceof Error ? error : new Error(String(error));
+                throw this.initError;
+            });
+        }
+        await this.initialized;
     }
     async init() {
         const dir = dirname(this.filePath);
@@ -83,16 +122,16 @@ export class FileStore {
         this.dirty = false;
     }
     async get(key) {
-        await this.initialized;
+        await this.ensureInitialized();
         return this.data.get(key) ?? null;
     }
     async set(key, value) {
-        await this.initialized;
+        await this.ensureInitialized();
         this.data.set(key, { ...value });
         await this.persist();
     }
     async bulkSet(records) {
-        await this.initialized;
+        await this.ensureInitialized();
         // Set all records in memory first (no disk I/O per record)
         for (const { key, value } of records) {
             this.data.set(key, { ...value });
@@ -100,8 +139,23 @@ export class FileStore {
         // Single persist operation for all records
         await this.persist();
     }
+    async bulkUpsert(records) {
+        await this.ensureInitialized();
+        // Upsert all records in memory first (no disk I/O per record)
+        for (const { key, value } of records) {
+            const existing = this.data.get(key);
+            if (existing) {
+                this.data.set(key, { ...existing, ...value });
+            }
+            else {
+                this.data.set(key, { ...value });
+            }
+        }
+        // Single persist operation for all records
+        await this.persist();
+    }
     async update(key, value) {
-        await this.initialized;
+        await this.ensureInitialized();
         const existing = this.data.get(key);
         if (existing) {
             this.data.set(key, { ...existing, ...value });
@@ -112,16 +166,16 @@ export class FileStore {
         await this.persist();
     }
     async delete(key) {
-        await this.initialized;
+        await this.ensureInitialized();
         this.data.delete(key);
         await this.persist();
     }
     async list(filter) {
-        await this.initialized;
+        await this.ensureInitialized();
         return applyStoreFilter(Array.from(this.data.values()), filter);
     }
     async count(filter) {
-        await this.initialized;
+        await this.ensureInitialized();
         // Apply only the where clause for counting (ignore limit/offset)
         const filtered = applyStoreFilter(Array.from(this.data.values()), {
             where: filter?.where,
@@ -129,7 +183,7 @@ export class FileStore {
         return filtered.length;
     }
     async clear() {
-        await this.initialized;
+        await this.ensureInitialized();
         this.data.clear();
         await this.persist();
     }

package/dist/stores/index.d.ts

@@ -1,6 +1,21 @@
+/**
+ * ---
+ * purpose: Store adapters - pluggable storage backends for pipeline data
+ * exports:
+ *   - StoreAdapter - interface for all stores
+ *   - MemoryStore, FileStore, PostgRESTStore - implementations
+ *   - createStore - factory function
+ * related:
+ *   - ./types.ts - StoreAdapter interface definition
+ *   - ./memory.ts - in-memory store (default)
+ *   - ./file.ts - JSON/CSV file store
+ *   - ./postgrest.ts - PostgREST API store
+ *   - ../interpreter/context.ts - stores registered in context
+ * ---
+ */
 export type { StoreAdapter, StoreFilter, StoreConfig } from './types.js';
 export { applyStoreFilter } from './types.js';
 export { MemoryStore } from './memory.js';
 export { FileStore, type FileStoreOptions } from './file.js';
 export { PostgRESTStore, PostgRESTError, type PostgRESTOptions } from './postgrest.js';
-export { createStore, resolveStoreType, type StoreType, type CreateStoreOptions } from './factory.js';
+export { createStore, resolveStoreType, type StoreType, type CreateStoreOptions, } from './factory.js';

package/dist/stores/index.js

@@ -1,5 +1,20 @@
+/**
+ * ---
+ * purpose: Store adapters - pluggable storage backends for pipeline data
+ * exports:
+ *   - StoreAdapter - interface for all stores
+ *   - MemoryStore, FileStore, PostgRESTStore - implementations
+ *   - createStore - factory function
+ * related:
+ *   - ./types.ts - StoreAdapter interface definition
+ *   - ./memory.ts - in-memory store (default)
+ *   - ./file.ts - JSON/CSV file store
+ *   - ./postgrest.ts - PostgREST API store
+ *   - ../interpreter/context.ts - stores registered in context
+ * ---
+ */
 export { applyStoreFilter } from './types.js';
 export { MemoryStore } from './memory.js';
 export { FileStore } from './file.js';
 export { PostgRESTStore, PostgRESTError } from './postgrest.js';
-export { createStore, resolveStoreType } from './factory.js';
+export { createStore, resolveStoreType, } from './factory.js';

package/dist/stores/memory.d.ts

@@ -9,6 +9,10 @@ export declare class MemoryStore implements StoreAdapter {
         key: string;
         value: Record<string, unknown>;
     }>): Promise<void>;
+    bulkUpsert(records: Array<{
+        key: string;
+        value: Record<string, unknown>;
+    }>): Promise<void>;
     update(key: string, value: Partial<Record<string, unknown>>): Promise<void>;
     delete(key: string): Promise<void>;
     list(filter?: StoreFilter): Promise<Record<string, unknown>[]>;

package/dist/stores/memory.js

@@ -16,6 +16,17 @@ export class MemoryStore {
             this.data.set(key, { ...value });
         }
     }
+    async bulkUpsert(records) {
+        for (const { key, value } of records) {
+            const existing = this.data.get(key);
+            if (existing) {
+                this.data.set(key, { ...existing, ...value });
+            }
+            else {
+                this.data.set(key, { ...value });
+            }
+        }
+    }
     async update(key, value) {
         const existing = this.data.get(key);
         if (existing) {

package/dist/stores/types.d.ts

@@ -1,3 +1,15 @@
+/**
+ * ---
+ * purpose: Store interface definitions - contract for all store adapters
+ * exports:
+ *   - StoreAdapter - CRUD interface (get, set, update, delete, list, count)
+ *   - StoreFilter - where/limit/offset for queries
+ *   - StoreConfig - store type configuration
+ * related:
+ *   - ./memory.ts, ./file.ts, ./postgrest.ts - implementations
+ *   - ../interpreter/step-handlers/store-handler.ts - uses StoreAdapter
+ * ---
+ */
 export interface StoreAdapter {
     get(key: string): Promise<Record<string, unknown> | null>;
     set(key: string, value: Record<string, unknown>): Promise<void>;
@@ -6,6 +18,11 @@ export interface StoreAdapter {
         key: string;
         value: Record<string, unknown>;
     }>): Promise<void>;
+    /** Bulk upsert multiple records at once - more efficient than individual updates */
+    bulkUpsert?(records: Array<{
+        key: string;
+        value: Record<string, unknown>;
+    }>): Promise<void>;
     update(key: string, value: Partial<Record<string, unknown>>): Promise<void>;
     delete(key: string): Promise<void>;
     list(filter?: StoreFilter): Promise<Record<string, unknown>[]>;

package/dist/stores/types.js

@@ -1,3 +1,15 @@
+/**
+ * ---
+ * purpose: Store interface definitions - contract for all store adapters
+ * exports:
+ *   - StoreAdapter - CRUD interface (get, set, update, delete, list, count)
+ *   - StoreFilter - where/limit/offset for queries
+ *   - StoreConfig - store type configuration
+ * related:
+ *   - ./memory.ts, ./file.ts, ./postgrest.ts - implementations
+ *   - ../interpreter/step-handlers/store-handler.ts - uses StoreAdapter
+ * ---
+ */
 /**
  * Apply filter criteria to a list of records.
  * Handles where clause, offset, and limit.

package/dist/trace/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Trace Module - Time-travel debugging for Reqon
+ *
+ * Provides execution tracing, replay, and debugging capabilities:
+ * - TraceRecorder: Captures execution state at each step
+ * - TraceStore: Persists traces for later analysis
+ * - TraceReplayer: Navigates and inspects recorded traces
+ */
+export type { TraceSnapshot, StoreSnapshot, LoopContext, ExecutionTrace } from './state.js';
+export { generateSnapshotId, createExecutionTrace, safeClone, truncateForTrace } from './state.js';
+export type { TraceStore } from './store.js';
+export { FileTraceStore, MemoryTraceStore } from './store.js';
+export type { TraceRecorderConfig } from './recorder.js';
+export { TraceRecorder, createTraceRecorder } from './recorder.js';
+export type { ReplaySession, ReplayStepResult, TimelineEvent, VariableChange, SnapshotDiff, } from './replay.js';
+export { TraceReplayer, createTraceReplayer } from './replay.js';

package/dist/trace/index.js

@@ -0,0 +1,12 @@
+/**
+ * Trace Module - Time-travel debugging for Reqon
+ *
+ * Provides execution tracing, replay, and debugging capabilities:
+ * - TraceRecorder: Captures execution state at each step
+ * - TraceStore: Persists traces for later analysis
+ * - TraceReplayer: Navigates and inspects recorded traces
+ */
+export { generateSnapshotId, createExecutionTrace, safeClone, truncateForTrace } from './state.js';
+export { FileTraceStore, MemoryTraceStore } from './store.js';
+export { TraceRecorder, createTraceRecorder } from './recorder.js';
+export { TraceReplayer, createTraceReplayer } from './replay.js';

package/dist/trace/recorder.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 type { ExecutionContext } from '../interpreter/context.js';
+import type { TraceStore } from './store.js';
+import { type ExecutionTrace, type TraceSnapshot, type LoopContext } from './state.js';
+export interface TraceRecorderConfig {
+    /** Execution ID (used as trace ID) */
+    executionId: string;
+    /** Mission name */
+    mission: string;
+    /** Trace mode */
+    mode: 'full' | 'minimal';
+    /** Store for persisting traces */
+    store: TraceStore;
+    /** Metadata to attach to trace */
+    metadata?: Record<string, unknown>;
+    /** Whether to stream snapshots (append as they happen) vs batch at end */
+    streaming?: boolean;
+    /** Max items to include in store samples */
+    maxStoreItems?: number;
+}
+/**
+ * Records execution state for time-travel debugging
+ */
+export declare class TraceRecorder {
+    private config;
+    private trace;
+    private snapshotIndex;
+    private currentLoopContext?;
+    constructor(config: TraceRecorderConfig);
+    /**
+     * Record a snapshot before step execution
+     */
+    recordBeforeStep(action: string, stepIndex: number, stepType: string, ctx: ExecutionContext): Promise<void>;
+    /**
+     * Record a snapshot after step execution
+     */
+    recordAfterStep(action: string, stepIndex: number, stepType: string, ctx: ExecutionContext, stepDuration: number, error?: string): Promise<void>;
+    /**
+     * Set loop context for subsequent snapshots
+     */
+    setLoopContext(context: LoopContext | undefined): void;
+    /**
+     * Finalize the trace (called when execution completes)
+     */
+    finalize(success: boolean): Promise<ExecutionTrace>;
+    /**
+     * Get the current trace (without finalizing)
+     */
+    getTrace(): ExecutionTrace;
+    /**
+     * Get a specific snapshot by index
+     */
+    getSnapshot(index: number): TraceSnapshot | undefined;
+    /**
+     * Get the total number of snapshots recorded
+     */
+    getSnapshotCount(): number;
+    private createSnapshot;
+    private captureVariables;
+    private captureStores;
+    private addSnapshot;
+}
+/**
+ * Create a trace recorder for an execution
+ */
+export declare function createTraceRecorder(config: TraceRecorderConfig): TraceRecorder;

package/dist/trace/recorder.js

@@ -0,0 +1,144 @@
+/**
+ * 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';
+/**
+ * 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
+     */
+    getSnapshotCount() {
+        return this.trace.snapshots.length;
+    }
+    createSnapshot(action, stepIndex, stepType, phase, ctx) {
+        const index = this.snapshotIndex++;
+        // Capture variables from context chain
+        const variables = this.captureVariables(ctx);
+        // Capture store states
+        const stores = this.captureStores(ctx);
+        // Capture response (truncated for large responses)
+        const response = this.config.mode === 'full' ? 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;
+    }
+    async addSnapshot(snapshot) {
+        this.trace.snapshots.push(snapshot);
+        // If streaming mode, persist immediately
+        if (this.config.streaming) {
+            await this.config.store.appendSnapshot(this.trace.id, snapshot);
+        }
+    }
+}
+/**
+ * Create a trace recorder for an execution
+ */
+export function createTraceRecorder(config) {
+    return new TraceRecorder(config);
+}