reqon-dsl 0.3.0 → 0.4.0

package/dist/stores/postgrest.d.ts

@@ -10,6 +10,17 @@ export interface PostgRESTOptions {
     primaryKey?: string;
     /** Optional schema (for Supabase, typically 'public') */
     schema?: string;
+    /**
+     * Per-request timeout in milliseconds (default: 30000). Every request is
+     * aborted after this elapses so a hung connection can't stall a mission.
+     */
+    timeoutMs?: number;
+    /**
+     * Opt-in guard for {@link PostgRESTStore.clear}, which issues a full-table
+     * DELETE. Defaults to false so a misconfigured store (e.g. a `sql` type
+     * resolving here by mistake) can't wipe a table.
+     */
+    allowFullTableClear?: boolean;
 }
 /**
  * PostgREST-compatible store adapter.
@@ -29,7 +40,24 @@ export declare class PostgRESTStore implements StoreAdapter {
     private baseUrl;
     private headers;
     private primaryKey;
+    private timeoutMs;
     constructor(options: PostgRESTOptions);
+    /** fetch wrapper that aborts the request once {@link timeoutMs} elapses. */
+    private request;
+    /**
+     * 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.
+     */
+    private validateField;
+    /**
+     * 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.
+     */
+    private formatFilterValue;
+    /** Append a validated, escaped where clause to the given params. */
+    private applyWhere;
     get(key: string): Promise<Record<string, unknown> | null>;
     set(key: string, value: Record<string, unknown>): Promise<void>;
     update(key: string, value: Partial<Record<string, unknown>>): Promise<void>;

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/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

@@ -14,3 +14,5 @@ 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

@@ -10,3 +10,4 @@ export { generateSnapshotId, createExecutionTrace, safeClone, truncateForTrace }
 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

@@ -57,12 +57,16 @@ export declare class TraceRecorder {
      */
     getSnapshot(index: number): TraceSnapshot | undefined;
     /**
-     * Get the total number of snapshots recorded
+     * 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;
 }
 /**

package/dist/trace/recorder.js

@@ -5,6 +5,7 @@
  * 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
  */
@@ -65,19 +66,24 @@ export class TraceRecorder {
         return this.trace.snapshots[index];
     }
     /**
-     * Get the total number of snapshots recorded
+     * 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.trace.snapshots.length;
+        return this.snapshotIndex;
     }
     createSnapshot(action, stepIndex, stepType, phase, ctx) {
         const index = this.snapshotIndex++;
-        // Capture variables from context chain
-        const variables = this.captureVariables(ctx);
+        // 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' ? truncateForTrace(safeClone(ctx.response)) : undefined;
+        const response = this.config.mode === 'full'
+            ? redactSecrets(truncateForTrace(safeClone(ctx.response)))
+            : undefined;
         return {
             id: generateSnapshotId(this.trace.id, index),
             index,
@@ -128,11 +134,18 @@ export class TraceRecorder {
         }
         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 streaming mode, persist immediately
         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);
+            }
         }
     }
 }

package/dist/trace/store.d.ts

@@ -35,6 +35,8 @@ export interface TraceStore {
 export declare class FileTraceStore implements TraceStore {
     private baseDir;
     private initialized;
+    /** Per-trace append serialization to prevent concurrent index collisions. */
+    private appendChain;
     constructor(baseDir?: string);
     private getTraceDir;
     private getMetadataPath;
@@ -43,6 +45,7 @@ export declare class FileTraceStore implements TraceStore {
     private deserializeSnapshot;
     save(trace: ExecutionTrace): Promise<void>;
     appendSnapshot(traceId: string, snapshot: TraceSnapshot): Promise<void>;
+    private doAppendSnapshot;
     load(id: string): Promise<ExecutionTrace | null>;
     loadSnapshot(traceId: string, snapshotIndex: number): Promise<TraceSnapshot | null>;
     listByMission(mission: string, limit?: number): Promise<ExecutionTrace[]>;
@@ -50,6 +53,9 @@ export declare class FileTraceStore implements TraceStore {
     delete(id: string): Promise<void>;
     findLatest(mission: string): Promise<ExecutionTrace | null>;
     getMetadata(id: string): Promise<Omit<ExecutionTrace, 'snapshots'> | null>;
+    /** Read the metadata file, returning the committed snapshot count and the
+     * trace metadata (snapshotCount stripped). */
+    private readMetadataRaw;
 }
 /**
  * In-memory trace store (for testing)