reqon-dsl 0.2.0 → 0.4.0

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,75 @@
+/**
+ * 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;
+    /** Per-trace append serialization to prevent concurrent index collisions. */
+    private appendChain;
+    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>;
+    private doAppendSnapshot;
+    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>;
+    /** Read the metadata file, returning the committed snapshot count and the
+     * trace metadata (snapshotCount stripped). */
+    private readMetadataRaw;
+}
+/**
+ * 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;
+}

package/dist/trace/store.js

@@ -0,0 +1,250 @@
+/**
+ * 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 { join } from 'node:path';
+import { safeJoin } from '../utils/path.js';
+import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from '../utils/file.js';
+/**
+ * File-based trace store
+ * Stores traces in .reqon-data/traces/ with separate files for metadata and snapshots
+ */
+export class FileTraceStore {
+    baseDir;
+    initialized;
+    /** Per-trace append serialization to prevent concurrent index collisions. */
+    appendChain = new Map();
+    constructor(baseDir = '.reqon-data/traces') {
+        this.baseDir = baseDir;
+        this.initialized = ensureDirectory(this.baseDir);
+    }
+    getTraceDir(id) {
+        // Confine the (DSL-influenced) trace id to the traces base directory.
+        return safeJoin(this.baseDir, id);
+    }
+    getMetadataPath(id) {
+        return join(this.getTraceDir(id), 'metadata.json');
+    }
+    getSnapshotPath(id, index) {
+        return join(this.getTraceDir(id), `snapshot_${index.toString().padStart(6, '0')}.json`);
+    }
+    async deserializeTrace(parsed) {
+        restoreDates(parsed, ['startedAt', 'completedAt']);
+        if (parsed.snapshots && Array.isArray(parsed.snapshots)) {
+            restoreDatesInArray(parsed.snapshots, ['timestamp']);
+        }
+        return parsed;
+    }
+    deserializeSnapshot(parsed) {
+        restoreDates(parsed, ['timestamp']);
+        return parsed;
+    }
+    async save(trace) {
+        await this.initialized;
+        const traceDir = this.getTraceDir(trace.id);
+        await ensureDirectory(traceDir);
+        // Save metadata separately from snapshots for efficient listing
+        const metadata = {
+            id: trace.id,
+            mission: trace.mission,
+            mode: trace.mode,
+            startedAt: trace.startedAt,
+            completedAt: trace.completedAt,
+            duration: trace.duration,
+            success: trace.success,
+            metadata: trace.metadata,
+            snapshotCount: trace.snapshots.length,
+        };
+        // Write all snapshots first, then metadata last. Metadata's snapshotCount
+        // acts as a commit pointer: a crash mid-save leaves either no metadata or
+        // the previous one, never a metadata that claims more snapshots than exist.
+        for (let i = 0; i < trace.snapshots.length; i++) {
+            await writeJsonFile(this.getSnapshotPath(trace.id, i), trace.snapshots[i], true, 0o600);
+        }
+        await writeJsonFile(this.getMetadataPath(trace.id), metadata, true, 0o600);
+    }
+    async appendSnapshot(traceId, snapshot) {
+        // Serialize appends per trace so two concurrent calls can't compute the
+        // same next index and clobber each other's snapshot file.
+        const run = (this.appendChain.get(traceId) ?? Promise.resolve()).then(() => this.doAppendSnapshot(traceId, snapshot));
+        // Keep the chain alive even if this append rejects.
+        this.appendChain.set(traceId, run.catch(() => { }));
+        return run;
+    }
+    async doAppendSnapshot(traceId, snapshot) {
+        await this.initialized;
+        const traceDir = this.getTraceDir(traceId);
+        await ensureDirectory(traceDir);
+        // Load current metadata to get snapshot count
+        const metadataPath = this.getMetadataPath(traceId);
+        const metadata = await readJsonFile(metadataPath);
+        let snapshotCount = 0;
+        if (metadata && typeof metadata.snapshotCount === 'number') {
+            snapshotCount = metadata.snapshotCount;
+        }
+        // Write the snapshot first, then commit the new count to metadata so a
+        // crash between the two leaves an uncommitted (ignored) snapshot, never a
+        // count that points past what's on disk.
+        await writeJsonFile(this.getSnapshotPath(traceId, snapshotCount), snapshot, true, 0o600);
+        if (metadata) {
+            metadata.snapshotCount = snapshotCount + 1;
+            await writeJsonFile(metadataPath, metadata, true, 0o600);
+        }
+    }
+    async load(id) {
+        await this.initialized;
+        const raw = await this.readMetadataRaw(id);
+        if (!raw)
+            return null;
+        const { snapshotCount, metadata } = raw;
+        // Load exactly the committed number of snapshots, by index. Globbing
+        // snapshot_*.json would silently include a half-written extra file or
+        // miss nothing about a gap; loading by the committed count guarantees the
+        // replayed trace matches what save/append actually committed.
+        const snapshots = [];
+        for (let i = 0; i < snapshotCount; i++) {
+            const parsed = await readJsonFile(this.getSnapshotPath(id, i));
+            if (!parsed) {
+                throw new Error(`Trace ${id} is inconsistent: metadata claims ${snapshotCount} snapshots ` +
+                    `but snapshot ${i} is missing.`);
+            }
+            snapshots.push(this.deserializeSnapshot(parsed));
+        }
+        return {
+            ...metadata,
+            snapshots,
+        };
+    }
+    async loadSnapshot(traceId, snapshotIndex) {
+        await this.initialized;
+        const snapshotPath = this.getSnapshotPath(traceId, snapshotIndex);
+        const parsed = await readJsonFile(snapshotPath);
+        return parsed ? this.deserializeSnapshot(parsed) : null;
+    }
+    async listByMission(mission, limit = 50) {
+        const all = await this.listRecent(limit * 2); // Load more to filter
+        return all.filter((t) => t.mission === mission).slice(0, limit);
+    }
+    async listRecent(limit = 50) {
+        await this.initialized;
+        const entries = await listFiles(this.baseDir, '');
+        const traces = [];
+        // Read metadata files from subdirectories
+        for (const entry of entries) {
+            if (entry.endsWith('metadata.json')) {
+                const parsed = await readJsonFile(entry);
+                if (parsed) {
+                    const trace = await this.deserializeTrace(parsed);
+                    // Return without snapshots for listing efficiency
+                    traces.push({ ...trace, snapshots: [] });
+                }
+            }
+        }
+        // Sort by start time, newest first
+        traces.sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime());
+        return traces.slice(0, limit);
+    }
+    async delete(id) {
+        await this.initialized;
+        const traceDir = this.getTraceDir(id);
+        const files = await listFiles(traceDir, '.json');
+        for (const file of files) {
+            await deleteFile(file);
+        }
+        // Note: Directory cleanup would require additional fs.rmdir
+    }
+    async findLatest(mission) {
+        const traces = await this.listByMission(mission, 1);
+        return traces[0] ?? null;
+    }
+    async getMetadata(id) {
+        const raw = await this.readMetadataRaw(id);
+        return raw ? raw.metadata : null;
+    }
+    /** Read the metadata file, returning the committed snapshot count and the
+     * trace metadata (snapshotCount stripped). */
+    async readMetadataRaw(id) {
+        await this.initialized;
+        const parsed = await readJsonFile(this.getMetadataPath(id));
+        if (!parsed)
+            return null;
+        restoreDates(parsed, ['startedAt', 'completedAt']);
+        const { snapshotCount, ...rest } = parsed;
+        return {
+            snapshotCount: typeof snapshotCount === 'number' ? snapshotCount : 0,
+            metadata: rest,
+        };
+    }
+}
+/**
+ * In-memory trace store (for testing)
+ */
+export class MemoryTraceStore {
+    traces = new Map();
+    async save(trace) {
+        this.traces.set(trace.id, JSON.parse(JSON.stringify(trace)));
+    }
+    async appendSnapshot(traceId, snapshot) {
+        const trace = this.traces.get(traceId);
+        if (trace) {
+            trace.snapshots.push(JSON.parse(JSON.stringify(snapshot)));
+        }
+    }
+    async load(id) {
+        const trace = this.traces.get(id);
+        if (!trace)
+            return null;
+        const restored = JSON.parse(JSON.stringify(trace));
+        restored.startedAt = new Date(restored.startedAt);
+        if (restored.completedAt) {
+            restored.completedAt = new Date(restored.completedAt);
+        }
+        for (const snapshot of restored.snapshots) {
+            snapshot.timestamp = new Date(snapshot.timestamp);
+        }
+        return restored;
+    }
+    async loadSnapshot(traceId, snapshotIndex) {
+        const trace = this.traces.get(traceId);
+        if (!trace || snapshotIndex >= trace.snapshots.length)
+            return null;
+        const snapshot = JSON.parse(JSON.stringify(trace.snapshots[snapshotIndex]));
+        snapshot.timestamp = new Date(snapshot.timestamp);
+        return snapshot;
+    }
+    async listByMission(mission, limit = 50) {
+        const all = await this.listRecent();
+        return all.filter((t) => t.mission === mission).slice(0, limit);
+    }
+    async listRecent(limit = 50) {
+        const traces = Array.from(this.traces.values()).map((t) => {
+            const restored = JSON.parse(JSON.stringify(t));
+            restored.startedAt = new Date(restored.startedAt);
+            if (restored.completedAt) {
+                restored.completedAt = new Date(restored.completedAt);
+            }
+            return { ...restored, snapshots: [] };
+        });
+        traces.sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime());
+        return traces.slice(0, limit);
+    }
+    async delete(id) {
+        this.traces.delete(id);
+    }
+    async findLatest(mission) {
+        const traces = await this.listByMission(mission, 1);
+        return traces[0] ?? null;
+    }
+    async getMetadata(id) {
+        const trace = await this.load(id);
+        if (!trace)
+            return null;
+        const { snapshots: _snapshots, ...metadata } = trace;
+        return metadata;
+    }
+    clear() {
+        this.traces.clear();
+    }
+}

package/dist/utils/deep-merge.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deep-merge for store upserts.
+ *
+ * A shallow `{ ...existing, ...incoming }` clobbers nested objects: merging
+ * `{ profile: { city: 'LA' } }` over `{ profile: { name: 'Alice' } }` drops
+ * `name`. deepMerge recurses into plain objects so sibling nested fields
+ * survive. Arrays and primitives are replaced wholesale (the incoming value
+ * wins), and neither input is mutated.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

package/dist/utils/deep-merge.js

@@ -0,0 +1,23 @@
+/**
+ * Deep-merge for store upserts.
+ *
+ * A shallow `{ ...existing, ...incoming }` clobbers nested objects: merging
+ * `{ profile: { city: 'LA' } }` over `{ profile: { name: 'Alice' } }` drops
+ * `name`. deepMerge recurses into plain objects so sibling nested fields
+ * survive. Arrays and primitives are replaced wholesale (the incoming value
+ * wins), and neither input is mutated.
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function deepMerge(target, source) {
+    const out = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        const existing = out[key];
+        out[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+    }
+    return out;
+}

package/dist/utils/file.d.ts

@@ -11,12 +11,21 @@ export declare function ensureParentDirectory(filePath: string): Promise<void>;
  */
 export declare function serialize(data: unknown, pretty?: boolean): string;
 /**
- * Write JSON data to a file
+ * Atomically write a file: write to a temp file, fsync it, then rename over
+ * the target. A crash or full disk mid-write leaves the original file intact
+ * rather than truncating it (the rename is atomic on POSIX/NTFS).
  */
-export declare function writeJsonFile(filePath: string, data: unknown, pretty?: boolean): Promise<void>;
+export declare function writeFileAtomic(filePath: string, content: string, mode?: number): Promise<void>;
+/** Synchronous counterpart to {@link writeFileAtomic} for flush/exit paths. */
+export declare function writeFileAtomicSync(filePath: string, content: string): void;
 /**
- * Read JSON data from a file
- * Returns null if file doesn't exist or is corrupted
+ * Write JSON data to a file atomically (durable against mid-write crashes).
+ */
+export declare function writeJsonFile(filePath: string, data: unknown, pretty?: boolean, mode?: number): Promise<void>;
+/**
+ * Read JSON data from a file.
+ * Returns null only if the file is absent; throws if it exists but is corrupt
+ * so a truncated/partial file is never silently treated as "empty".
  */
 export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
 /**

package/dist/utils/file.js

@@ -1,5 +1,8 @@
-import { mkdir, readFile, writeFile, access, readdir, unlink } from 'node:fs/promises';
+import { mkdir, readFile, access, readdir, unlink, rename, open } from 'node:fs/promises';
+import { openSync, writeSync, fsyncSync, closeSync, renameSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+// Monotonic counter to keep concurrent temp-file names unique within a process.
+let tmpCounter = 0;
 /**
  * Ensure a directory exists, creating it if necessary
  */
@@ -24,22 +27,79 @@ export function serialize(data, pretty = true) {
     return pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
 }
 /**
- * Write JSON data to a file
+ * Atomically write a file: write to a temp file, fsync it, then rename over
+ * the target. A crash or full disk mid-write leaves the original file intact
+ * rather than truncating it (the rename is atomic on POSIX/NTFS).
  */
-export async function writeJsonFile(filePath, data, pretty = true) {
-    await writeFile(filePath, serialize(data, pretty), 'utf-8');
+export async function writeFileAtomic(filePath, content, mode) {
+    const tmpPath = `${filePath}.${process.pid}.${tmpCounter++}.tmp`;
+    const handle = await open(tmpPath, 'w', mode);
+    try {
+        await handle.writeFile(content, 'utf-8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(tmpPath, filePath);
+    }
+    catch (err) {
+        await unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+/** Synchronous counterpart to {@link writeFileAtomic} for flush/exit paths. */
+export function writeFileAtomicSync(filePath, content) {
+    const tmpPath = `${filePath}.${process.pid}.${tmpCounter++}.tmp`;
+    const fd = openSync(tmpPath, 'w');
+    try {
+        writeSync(fd, content);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        throw err;
+    }
+}
+/**
+ * Write JSON data to a file atomically (durable against mid-write crashes).
+ */
+export async function writeJsonFile(filePath, data, pretty = true, mode) {
+    await writeFileAtomic(filePath, serialize(data, pretty), mode);
 }
 /**
- * Read JSON data from a file
- * Returns null if file doesn't exist or is corrupted
+ * Read JSON data from a file.
+ * Returns null only if the file is absent; throws if it exists but is corrupt
+ * so a truncated/partial file is never silently treated as "empty".
  */
 export async function readJsonFile(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
     try {
-        const content = await readFile(filePath, 'utf-8');
         return JSON.parse(content);
     }
-    catch {
-        return null;
+    catch (err) {
+        throw new Error(`Corrupt JSON in ${filePath}: ${err.message}`, { cause: err });
     }
 }
 /**
@@ -48,9 +108,7 @@ export async function readJsonFile(filePath) {
 export async function listFiles(dir, extension) {
     try {
         const entries = await readdir(dir);
-        const filtered = extension
-            ? entries.filter((f) => f.endsWith(extension))
-            : entries;
+        const filtered = extension ? entries.filter((f) => f.endsWith(extension)) : entries;
         return filtered.map((f) => join(dir, f));
     }
     catch {

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export { sleep } from './async.js';
-export { extractNestedValue, traversePath } from './path.js';
+export { extractNestedValue, traversePath, safeJoin, sanitizeSegment, PathTraversalError, } from './path.js';
 export { type Logger, ConsoleLogger, SilentLogger, createLogger } from './logger.js';
 export { ensureDirectory, ensureParentDirectory, serialize, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from './file.js';
+export { isRecord, isObject, isArrayOf, isString, isNumber, isBoolean, isDefined, isPresent, getProperty, getNestedProperty, hasProperty, hasTypedProperty, } from './type-guards.js';

package/dist/utils/index.js

@@ -1,4 +1,5 @@
 export { sleep } from './async.js';
-export { extractNestedValue, traversePath } from './path.js';
+export { extractNestedValue, traversePath, safeJoin, sanitizeSegment, PathTraversalError, } from './path.js';
 export { ConsoleLogger, SilentLogger, createLogger } from './logger.js';
 export { ensureDirectory, ensureParentDirectory, serialize, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, restoreDatesInArray, } from './file.js';
+export { isRecord, isObject, isArrayOf, isString, isNumber, isBoolean, isDefined, isPresent, getProperty, getNestedProperty, hasProperty, hasTypedProperty, } from './type-guards.js';

package/dist/utils/long-timeout.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Timers for delays beyond Node's 32-bit setTimeout limit.
+ *
+ * Node stores the delay in a 32-bit signed int: anything over 2_147_483_647 ms
+ * (~24.8 days) overflows and the callback fires almost immediately. A multi-week
+ * webhook wait or pause would therefore time out at once. `setLongTimeout`
+ * chains native timeouts so arbitrarily long delays fire at the right time.
+ */
+/** Largest delay (ms) Node's setTimeout handles without overflowing. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+export interface LongTimeout {
+    /** Cancel the pending timeout. */
+    clear(): void;
+}
+/**
+ * Schedule `callback` to run after `delayMs`, correctly handling delays larger
+ * than {@link MAX_TIMEOUT_MS} by chaining native timeouts.
+ */
+export declare function setLongTimeout(callback: () => void, delayMs: number): LongTimeout;

package/dist/utils/long-timeout.js

@@ -0,0 +1,33 @@
+/**
+ * Timers for delays beyond Node's 32-bit setTimeout limit.
+ *
+ * Node stores the delay in a 32-bit signed int: anything over 2_147_483_647 ms
+ * (~24.8 days) overflows and the callback fires almost immediately. A multi-week
+ * webhook wait or pause would therefore time out at once. `setLongTimeout`
+ * chains native timeouts so arbitrarily long delays fire at the right time.
+ */
+/** Largest delay (ms) Node's setTimeout handles without overflowing. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * Schedule `callback` to run after `delayMs`, correctly handling delays larger
+ * than {@link MAX_TIMEOUT_MS} by chaining native timeouts.
+ */
+export function setLongTimeout(callback, delayMs) {
+    let remaining = Math.max(0, delayMs);
+    let timer;
+    const schedule = () => {
+        if (remaining <= MAX_TIMEOUT_MS) {
+            timer = setTimeout(callback, remaining);
+        }
+        else {
+            remaining -= MAX_TIMEOUT_MS;
+            timer = setTimeout(schedule, MAX_TIMEOUT_MS);
+        }
+    };
+    schedule();
+    return {
+        clear() {
+            clearTimeout(timer);
+        },
+    };
+}