reqon-dsl 0.2.0 → 0.4.0

package/dist/stores/postgrest.js

@@ -1,3 +1,17 @@
+/** PostgREST query parameters that are operators/modifiers, not columns. */
+const RESERVED_QUERY_KEYS = new Set([
+    'or',
+    'and',
+    'not',
+    'select',
+    'order',
+    'limit',
+    'offset',
+    'on_conflict',
+    'columns',
+]);
+/** A bare, safe column identifier: no operators, separators, or grouping. */
+const SAFE_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
  * PostgREST-compatible store adapter.
  * Works with Supabase, standalone PostgREST, or any PostgREST-compatible API.
@@ -16,26 +30,77 @@ export class PostgRESTStore {
     baseUrl;
     headers;
     primaryKey;
+    timeoutMs;
     constructor(options) {
         this.options = options;
         // Normalize URL (remove trailing slash)
         const url = options.url.replace(/\/$/, '');
         this.baseUrl = `${url}/${options.table}`;
         this.primaryKey = options.primaryKey ?? 'id';
+        this.timeoutMs = options.timeoutMs ?? 30000;
         this.headers = {
             'Content-Type': 'application/json',
-            'apikey': options.apiKey,
-            'Authorization': `Bearer ${options.apiKey}`,
-            'Prefer': 'return=representation',
+            apikey: options.apiKey,
+            Authorization: `Bearer ${options.apiKey}`,
+            Prefer: 'return=representation',
         };
         if (options.schema) {
             this.headers['Accept-Profile'] = options.schema;
             this.headers['Content-Profile'] = options.schema;
         }
     }
+    /** fetch wrapper that aborts the request once {@link timeoutMs} elapses. */
+    async request(url, init) {
+        try {
+            return await fetch(url, { ...init, signal: AbortSignal.timeout(this.timeoutMs) });
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === 'TimeoutError') {
+                throw new PostgRESTError(`Request timed out after ${this.timeoutMs}ms`, 0);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Reject a where-clause field unless it is a plain column identifier. This
+     * stops a key such as `or` or `id,or=(...)` from being concatenated into the
+     * query string and reinterpreted as a PostgREST operator.
+     */
+    validateField(field) {
+        if (!SAFE_FIELD.test(field) || RESERVED_QUERY_KEYS.has(field.toLowerCase())) {
+            throw new PostgRESTError(`Unsafe filter field name: ${JSON.stringify(field)}`, 0);
+        }
+    }
+    /**
+     * Render a where-clause value as a PostgREST operand. Strings containing
+     * reserved characters are wrapped in a quoted operand (with `"` and `\`
+     * escaped) so they can't be parsed as list/group syntax.
+     */
+    formatFilterValue(value) {
+        if (value === null)
+            return 'is.null';
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return `eq.${value}`;
+        if (typeof value === 'string') {
+            if (/[,.()"\\:]|\s/.test(value)) {
+                return `eq."${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+            }
+            return `eq.${value}`;
+        }
+        // Complex values: JSON-encode, then quote as a string operand.
+        const json = JSON.stringify(value);
+        return `eq."${json.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    }
+    /** Append a validated, escaped where clause to the given params. */
+    applyWhere(params, where) {
+        for (const [field, value] of Object.entries(where)) {
+            this.validateField(field);
+            params.append(field, this.formatFilterValue(value));
+        }
+    }
     async get(key) {
         const url = `${this.baseUrl}?${this.primaryKey}=eq.${encodeURIComponent(key)}&limit=1`;
-        const response = await fetch(url, {
+        const response = await this.request(url, {
             method: 'GET',
             headers: this.headers,
         });
@@ -48,11 +113,11 @@ export class PostgRESTStore {
     async set(key, value) {
         // Upsert using PostgREST's on_conflict resolution
         const record = { ...value, [this.primaryKey]: key };
-        const response = await fetch(this.baseUrl, {
+        const response = await this.request(this.baseUrl, {
             method: 'POST',
             headers: {
                 ...this.headers,
-                'Prefer': 'resolution=merge-duplicates,return=representation',
+                Prefer: 'resolution=merge-duplicates,return=representation',
             },
             body: JSON.stringify(record),
         });
@@ -63,7 +128,7 @@ export class PostgRESTStore {
     }
     async update(key, value) {
         const url = `${this.baseUrl}?${this.primaryKey}=eq.${encodeURIComponent(key)}`;
-        const response = await fetch(url, {
+        const response = await this.request(url, {
             method: 'PATCH',
             headers: this.headers,
             body: JSON.stringify(value),
@@ -75,7 +140,7 @@ export class PostgRESTStore {
     }
     async delete(key) {
         const url = `${this.baseUrl}?${this.primaryKey}=eq.${encodeURIComponent(key)}`;
-        const response = await fetch(url, {
+        const response = await this.request(url, {
             method: 'DELETE',
             headers: this.headers,
         });
@@ -88,21 +153,7 @@ export class PostgRESTStore {
         const params = new URLSearchParams();
         // Apply where clause
         if (filter?.where) {
-            for (const [field, value] of Object.entries(filter.where)) {
-                if (value === null) {
-                    params.append(field, 'is.null');
-                }
-                else if (typeof value === 'string') {
-                    params.append(field, `eq.${value}`);
-                }
-                else if (typeof value === 'number' || typeof value === 'boolean') {
-                    params.append(field, `eq.${value}`);
-                }
-                else {
-                    // For complex values, try JSON
-                    params.append(field, `eq.${JSON.stringify(value)}`);
-                }
-            }
+            this.applyWhere(params, filter.where);
         }
         // Apply pagination
         if (filter?.limit) {
@@ -113,7 +164,7 @@ export class PostgRESTStore {
         }
         const queryString = params.toString();
         const url = queryString ? `${this.baseUrl}?${queryString}` : this.baseUrl;
-        const response = await fetch(url, {
+        const response = await this.request(url, {
             method: 'GET',
             headers: this.headers,
         });
@@ -124,10 +175,13 @@ export class PostgRESTStore {
         return response.json();
     }
     async clear() {
+        if (!this.options.allowFullTableClear) {
+            throw new PostgRESTError('Refusing full-table delete: set allowFullTableClear to enable clear()', 0);
+        }
         // Delete all records - PostgREST requires a filter, so we use a always-true condition
         // This deletes where primary key is not null (i.e., all records)
         const url = `${this.baseUrl}?${this.primaryKey}=not.is.null`;
-        const response = await fetch(url, {
+        const response = await this.request(url, {
             method: 'DELETE',
             headers: this.headers,
         });
@@ -142,11 +196,11 @@ export class PostgRESTStore {
     async bulkInsert(records) {
         if (records.length === 0)
             return;
-        const response = await fetch(this.baseUrl, {
+        const response = await this.request(this.baseUrl, {
             method: 'POST',
             headers: {
                 ...this.headers,
-                'Prefer': 'resolution=merge-duplicates',
+                Prefer: 'resolution=merge-duplicates',
             },
             body: JSON.stringify(records),
         });
@@ -162,21 +216,14 @@ export class PostgRESTStore {
         const params = new URLSearchParams();
         params.append('select', 'count');
         if (filter?.where) {
-            for (const [field, value] of Object.entries(filter.where)) {
-                if (value === null) {
-                    params.append(field, 'is.null');
-                }
-                else {
-                    params.append(field, `eq.${value}`);
-                }
-            }
+            this.applyWhere(params, filter.where);
         }
         const url = `${this.baseUrl}?${params.toString()}`;
-        const response = await fetch(url, {
+        const response = await this.request(url, {
             method: 'GET',
             headers: {
                 ...this.headers,
-                'Prefer': 'count=exact',
+                Prefer: 'count=exact',
             },
         });
         if (!response.ok) {

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/sync/index.d.ts

@@ -1,4 +1,5 @@
-export type { SyncCheckpoint, SyncState, SinceResolution, SinceDateFormat, } from './state.js';
-export { generateCheckpointKey, formatSinceDate, parseSinceDate, EPOCH, } from './state.js';
+export type { SyncCheckpoint, SyncState, SinceResolution, SinceDateFormat } from './state.js';
+export { generateCheckpointKey, formatSinceDate, parseSinceDate, EPOCH } from './state.js';
 export type { SyncStore } from './store.js';
 export { FileSyncStore, MemorySyncStore } from './store.js';
+export { LogBackedSyncStore } from './log-store.js';

package/dist/sync/index.js

@@ -1,2 +1,3 @@
-export { generateCheckpointKey, formatSinceDate, parseSinceDate, EPOCH, } from './state.js';
+export { generateCheckpointKey, formatSinceDate, parseSinceDate, EPOCH } from './state.js';
 export { FileSyncStore, MemorySyncStore } from './store.js';
+export { LogBackedSyncStore } from './log-store.js';

package/dist/sync/log-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Log-backed sync store: incremental-sync checkpoints as a view over the
+ * execution log.
+ *
+ * In durable mode the execution log is the single source of truth — a sync's
+ * progress is recorded as a `checkpoint.advanced` event alongside everything
+ * else, so it survives a crash and resumes atomically with the run. This
+ * adapter reads `getLastSync`/checkpoint state back out of those events
+ * (newest-per-key, monotonic by `syncedAt`) instead of a separate sync file.
+ *
+ * Writes go through the log, not here: the executor appends `checkpoint.advanced`
+ * when a sync's fetched data is durably stored, so {@link recordSync} is a no-op.
+ */
+import type { ExecutionLogStore } from '../execution-log/index.js';
+import type { SyncStore } from './store.js';
+import type { SyncCheckpoint } from './state.js';
+export declare class LogBackedSyncStore implements SyncStore {
+    private log;
+    private mission?;
+    constructor(log: ExecutionLogStore, mission?: string | undefined);
+    private checkpoint;
+    getLastSync(key: string): Promise<Date>;
+    getCheckpoint(key: string): Promise<SyncCheckpoint | null>;
+    list(): Promise<SyncCheckpoint[]>;
+    /** No-op: the log (via `checkpoint.advanced`) is the write path. */
+    recordSync(_checkpoint: SyncCheckpoint): Promise<void>;
+    /** Clearing a log-derived checkpoint isn't supported (the log is append-only). */
+    clear(): Promise<void>;
+    clearAll(): Promise<void>;
+}

package/dist/sync/log-store.js

@@ -0,0 +1,45 @@
+import { EPOCH } from './state.js';
+export class LogBackedSyncStore {
+    log;
+    mission;
+    constructor(log, mission) {
+        this.log = log;
+        this.mission = mission;
+    }
+    async checkpoint(key) {
+        const records = await this.log.listCheckpoints(this.mission);
+        const record = records.find((r) => r.key === key);
+        if (!record)
+            return null;
+        return {
+            key: record.key,
+            syncedAt: new Date(record.syncedAt),
+            recordCount: record.recordCount,
+            cursor: record.cursor,
+            mission: record.mission,
+            executionId: record.executionId,
+        };
+    }
+    async getLastSync(key) {
+        return (await this.checkpoint(key))?.syncedAt ?? EPOCH;
+    }
+    async getCheckpoint(key) {
+        return this.checkpoint(key);
+    }
+    async list() {
+        const records = await this.log.listCheckpoints(this.mission);
+        return records.map((r) => ({
+            key: r.key,
+            syncedAt: new Date(r.syncedAt),
+            recordCount: r.recordCount,
+            cursor: r.cursor,
+            mission: r.mission,
+            executionId: r.executionId,
+        }));
+    }
+    /** No-op: the log (via `checkpoint.advanced`) is the write path. */
+    async recordSync(_checkpoint) { }
+    /** Clearing a log-derived checkpoint isn't supported (the log is append-only). */
+    async clear() { }
+    async clearAll() { }
+}

package/dist/sync/store.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { EPOCH } from './state.js';
-import { ensureParentDirectory, writeJsonFile, readJsonFile, restoreDates, } from '../utils/file.js';
+import { ensureParentDirectory, writeJsonFile, readJsonFile, restoreDates } from '../utils/file.js';
 /**
  * File-based sync store
  * Stores sync state in .reqon-data/sync/{mission}.json

package/dist/trace/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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';
+export type { LogTimelineEntry, LogTraceSummary } from './log-view.js';
+export { LogTraceView, traceTimelineFromLog } from './log-view.js';

package/dist/trace/index.js

@@ -0,0 +1,13 @@
+/**
+ * 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';
+export { LogTraceView, traceTimelineFromLog } from './log-view.js';

package/dist/trace/log-view.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Trace as a view over the execution log.
+ *
+ * Time-travel debugging and the audit trail fall straight out of the
+ * append-only log: the ordered sequence of events *is* the trace. This module
+ * derives a navigable timeline and a folded summary from `StoredEvent[]`, so a
+ * run's history is reconstructable from the log with no separate trace store.
+ *
+ * Scope: the log records the structural timeline (steps, effects, checkpoints,
+ * pauses, errors), which is what time-travel navigation and audit need. The
+ * richer variable-level snapshots remain the job of the opt-in {@link TraceRecorder}.
+ */
+import type { ExecutionLogStore, StoredEvent, ExecutionEventType } from '../execution-log/index.js';
+import { foldLog } from '../execution-log/index.js';
+/** One step in the timeline view, derived from a single log event. */
+export interface LogTimelineEntry {
+    /** Sequence within the execution (the time-travel cursor). */
+    seq: number;
+    /** Recorded wall-clock time (ISO 8601). */
+    at: string;
+    /** The underlying event type. */
+    type: ExecutionEventType;
+    /** Action name, for step events. */
+    action?: string;
+    /** Step identity, for step/effect events. */
+    step?: string;
+    /** Step kind (fetch, store, …), for step events. */
+    stepType?: string;
+    /** Attempt number, for step/effect events. */
+    attempt?: number;
+    /** Human-readable summary of this entry. */
+    detail?: string;
+}
+/** A folded summary of a run, for the trace overview. */
+export interface LogTraceSummary {
+    status: ReturnType<typeof foldLog>['status'];
+    totalEvents: number;
+    stepsCompleted: number;
+    effectsApplied: number;
+    checkpoints: number;
+    pendingPauseId?: string;
+    error?: string;
+}
+/** Build an ordered, navigable timeline from a run's log events. */
+export declare function traceTimelineFromLog(events: StoredEvent[]): LogTimelineEntry[];
+/**
+ * Navigable, log-backed trace for one execution: the timeline and a folded
+ * summary, read straight from the execution log.
+ */
+export declare class LogTraceView {
+    private log;
+    private executionId;
+    constructor(log: ExecutionLogStore, executionId: string);
+    events(): Promise<StoredEvent[]>;
+    timeline(): Promise<LogTimelineEntry[]>;
+    summary(): Promise<LogTraceSummary>;
+}

package/dist/trace/log-view.js

@@ -0,0 +1,76 @@
+import { foldLog } from '../execution-log/index.js';
+function describe(event) {
+    switch (event.type) {
+        case 'mission.started':
+            return `mission ${event.mission} started`;
+        case 'step.started':
+            return `${event.action}: ${event.stepType} step started`;
+        case 'step.completed':
+            return `step ${event.stepId} completed`;
+        case 'effect.applied':
+            return `${event.effectType} effect applied`;
+        case 'checkpoint.advanced':
+            return `checkpoint ${event.key} -> ${event.syncedAt}`;
+        case 'pause.created':
+            return `paused (${event.pauseId})`;
+        case 'pause.resumed':
+            return `resumed by ${event.resumedBy}`;
+        case 'mission.completed':
+            return 'mission completed';
+        case 'mission.failed':
+            return `mission failed: ${event.error}`;
+        default:
+            return undefined;
+    }
+}
+/** Build an ordered, navigable timeline from a run's log events. */
+export function traceTimelineFromLog(events) {
+    return events.map((event) => {
+        const entry = {
+            seq: event.seq,
+            at: event.at,
+            type: event.type,
+            detail: describe(event),
+        };
+        if ('action' in event)
+            entry.action = event.action;
+        if ('stepId' in event)
+            entry.step = event.stepId;
+        if ('stepType' in event)
+            entry.stepType = event.stepType;
+        if ('attempt' in event)
+            entry.attempt = event.attempt;
+        return entry;
+    });
+}
+/**
+ * Navigable, log-backed trace for one execution: the timeline and a folded
+ * summary, read straight from the execution log.
+ */
+export class LogTraceView {
+    log;
+    executionId;
+    constructor(log, executionId) {
+        this.log = log;
+        this.executionId = executionId;
+    }
+    async events() {
+        return this.log.read(this.executionId);
+    }
+    async timeline() {
+        return traceTimelineFromLog(await this.events());
+    }
+    async summary() {
+        const events = await this.events();
+        const folded = foldLog(events);
+        return {
+            status: folded.status,
+            totalEvents: events.length,
+            stepsCompleted: folded.completedSteps.size,
+            effectsApplied: folded.appliedEffects.size,
+            checkpoints: folded.checkpoints.size,
+            pendingPauseId: folded.pendingPauseId,
+            error: folded.error,
+        };
+    }
+}

package/dist/trace/recorder.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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. 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(): number;
+    private createSnapshot;
+    private captureVariables;
+    private captureStores;
+    /** Cap on snapshots kept in memory while streaming (each is already on disk). */
+    private static readonly MAX_STREAMED_IN_MEMORY;
+    private addSnapshot;
+}
+/**
+ * Create a trace recorder for an execution
+ */
+export declare function createTraceRecorder(config: TraceRecorderConfig): TraceRecorder;