ppef 1.0.0 → 1.1.0

package/dist/executor/memory-monitor.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Memory Monitoring for Experiment Execution
+ *
+ * Tracks memory usage during experiment execution to:
+ * 1. Detect memory leaks and excessive consumption
+ * 2. Provide early warning before OOM kills
+ * 3. Record memory statistics in provenance data
+ * 4. Enable automatic throttling or abort on memory pressure
+ */
+/**
+ * Memory usage statistics.
+ */
+export interface MemoryStats {
+    /** Resident set size in bytes (actual physical memory used) */
+    rssBytes: number;
+    /** Total heap size in bytes (allocated + unused) */
+    heapTotalBytes: number;
+    /** Heap used in bytes (actually used) */
+    heapUsedBytes: number;
+    /** External memory in bytes (C++ objects, etc) */
+    externalBytes: number;
+    /** Array buffers in bytes */
+    arrayBuffersBytes: number;
+    /** RSS in MB for human readability */
+    rssMb: number;
+    /** Heap usage percentage */
+    heapUsagePercent: number;
+    /** Timestamp when stats were collected */
+    timestamp: number;
+}
+/**
+ * Memory warning levels.
+ */
+export declare enum MemoryWarningLevel {
+    /** No warning (memory usage is normal) */
+    NORMAL = "normal",
+    /** Warning (memory usage is elevated) */
+    WARNING = "warning",
+    /** Critical (memory usage is dangerously high) */
+    CRITICAL = "critical",
+    /** Emergency (process is near OOM) */
+    EMERGENCY = "emergency"
+}
+/**
+ * Memory monitoring configuration.
+ */
+export interface MemoryMonitorConfig {
+    /** Warning threshold (MB) - default: 1GB */
+    warningThresholdMb: number;
+    /** Critical threshold (MB) - default: 2GB */
+    criticalThresholdMb: number;
+    /** Emergency threshold (MB) - default: 80% of system memory */
+    emergencyThresholdMb: number;
+    /** Whether to log memory usage */
+    verbose: boolean;
+    /** Callback when warning level changes */
+    onWarningLevelChange?: (level: MemoryWarningLevel, stats: MemoryStats) => void;
+}
+/**
+ * Default memory monitoring configuration.
+ */
+export declare const DEFAULT_MEMORY_CONFIG: MemoryMonitorConfig;
+/**
+ * Memory monitor for tracking usage during execution.
+ */
+export declare class MemoryMonitor {
+    private readonly config;
+    private currentLevel;
+    private startTime;
+    constructor(config?: Partial<MemoryMonitorConfig>);
+    /**
+     * Get current memory usage statistics.
+     */
+    getStats(): MemoryStats;
+    /**
+     * Get current warning level based on memory usage.
+     * @param stats
+     */
+    getWarningLevel(stats?: MemoryStats): MemoryWarningLevel;
+    /**
+     * Check memory usage and trigger warnings if needed.
+     *
+     * @returns Current warning level
+     */
+    check(): MemoryWarningLevel;
+    /**
+     * Log memory warning with details.
+     * @param level
+     * @param stats
+     */
+    private logWarning;
+    /**
+     * Create a memory snapshot for provenance tracking.
+     */
+    snapshot(): MemoryStats;
+    /**
+     * Format memory stats for logging.
+     * @param stats
+     */
+    format(stats?: MemoryStats): string;
+}
+/**
+ * Get or create the global memory monitor.
+ * @param config
+ */
+export declare const getGlobalMemoryMonitor: (config?: Partial<MemoryMonitorConfig>) => MemoryMonitor;
+/**
+ * Check memory usage using the global monitor.
+ */
+export declare const checkMemoryUsage: () => MemoryWarningLevel;
+/**
+ * Get current memory stats using the global monitor.
+ */
+export declare const getMemoryStats: () => MemoryStats;
+//# sourceMappingURL=memory-monitor.d.ts.map

package/dist/executor/memory-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.d.ts","sourceRoot":"","sources":["../../src/executor/memory-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IAEvB,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IAEtB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IAEtB,6BAA6B;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAE1B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IAEzB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,oBAAY,kBAAkB;IAC7B,0CAA0C;IAC1C,MAAM,WAAW;IAEjB,yCAAyC;IACzC,OAAO,YAAY;IAEnB,kDAAkD;IAClD,QAAQ,aAAa;IAErB,sCAAsC;IACtC,SAAS,cAAc;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,CAAC;IAE3B,6CAA6C;IAC7C,mBAAmB,EAAE,MAAM,CAAC;IAE5B,+DAA+D;IAC/D,oBAAoB,EAAE,MAAM,CAAC;IAE7B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IAEjB,0CAA0C;IAC1C,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/E;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAKnC,CAAC;AAEF;;GAEG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,YAAY,CAAiD;IACrE,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAKjD;;OAEG;IACH,QAAQ,IAAI,WAAW;IA0BvB;;;OAGG;IACH,eAAe,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,kBAAkB;IAexD;;;;OAIG;IACH,KAAK,IAAI,kBAAkB;IAoB3B;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAkBlB;;OAEG;IACH,QAAQ,IAAI,WAAW;IAIvB;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM;CAInC;AAOD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,OAAO,CAAC,mBAAmB,CAAC,KAAG,aAG9E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAO,kBAGnC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,QAAO,WAGjC,CAAC"}

package/dist/executor/memory-monitor.js

@@ -0,0 +1,168 @@
+/**
+ * Memory Monitoring for Experiment Execution
+ *
+ * Tracks memory usage during experiment execution to:
+ * 1. Detect memory leaks and excessive consumption
+ * 2. Provide early warning before OOM kills
+ * 3. Record memory statistics in provenance data
+ * 4. Enable automatic throttling or abort on memory pressure
+ */
+import { hrtime } from "node:process";
+/**
+ * Memory warning levels.
+ */
+export var MemoryWarningLevel;
+(function (MemoryWarningLevel) {
+    /** No warning (memory usage is normal) */
+    MemoryWarningLevel["NORMAL"] = "normal";
+    /** Warning (memory usage is elevated) */
+    MemoryWarningLevel["WARNING"] = "warning";
+    /** Critical (memory usage is dangerously high) */
+    MemoryWarningLevel["CRITICAL"] = "critical";
+    /** Emergency (process is near OOM) */
+    MemoryWarningLevel["EMERGENCY"] = "emergency";
+})(MemoryWarningLevel || (MemoryWarningLevel = {}));
+/**
+ * Default memory monitoring configuration.
+ */
+export const DEFAULT_MEMORY_CONFIG = {
+    warningThresholdMb: 1024, // 1GB
+    criticalThresholdMb: 2048, // 2GB
+    emergencyThresholdMb: Math.floor((Number(process.env.MEMORY_LIMIT_MB) || 16_384) * 0.8), // 80% of limit or 13GB
+    verbose: false,
+};
+/**
+ * Memory monitor for tracking usage during execution.
+ */
+export class MemoryMonitor {
+    config;
+    currentLevel = MemoryWarningLevel.NORMAL;
+    startTime;
+    constructor(config) {
+        this.config = { ...DEFAULT_MEMORY_CONFIG, ...config };
+        this.startTime = hrtime.bigint();
+    }
+    /**
+     * Get current memory usage statistics.
+     */
+    getStats() {
+        const mem = process.memoryUsage();
+        // RSS is already in bytes on most platforms
+        const rssBytes = mem.rss;
+        const rssMb = rssBytes / (1024 * 1024);
+        const heapTotalBytes = mem.heapTotal;
+        const heapUsedBytes = mem.heapUsed;
+        const heapUsagePercent = (heapUsedBytes / heapTotalBytes) * 100;
+        // Calculate elapsed time in milliseconds
+        const elapsedHr = hrtime.bigint() - this.startTime;
+        const timestamp = Number(elapsedHr) / 1_000_000;
+        return {
+            rssBytes,
+            heapTotalBytes,
+            heapUsedBytes,
+            externalBytes: mem.external,
+            arrayBuffersBytes: mem.arrayBuffers,
+            rssMb,
+            heapUsagePercent,
+            timestamp,
+        };
+    }
+    /**
+     * Get current warning level based on memory usage.
+     * @param stats
+     */
+    getWarningLevel(stats) {
+        const current = stats ?? this.getStats();
+        if (current.rssMb >= this.config.emergencyThresholdMb) {
+            return MemoryWarningLevel.EMERGENCY;
+        }
+        if (current.rssMb >= this.config.criticalThresholdMb) {
+            return MemoryWarningLevel.CRITICAL;
+        }
+        if (current.rssMb >= this.config.warningThresholdMb) {
+            return MemoryWarningLevel.WARNING;
+        }
+        return MemoryWarningLevel.NORMAL;
+    }
+    /**
+     * Check memory usage and trigger warnings if needed.
+     *
+     * @returns Current warning level
+     */
+    check() {
+        const stats = this.getStats();
+        const level = this.getWarningLevel(stats);
+        // Trigger callback if level changed
+        if (level !== this.currentLevel) {
+            this.currentLevel = level;
+            if (this.config.onWarningLevelChange) {
+                this.config.onWarningLevelChange(level, stats);
+            }
+        }
+        // Log warning if verbose
+        if (this.config.verbose && level !== MemoryWarningLevel.NORMAL) {
+            this.logWarning(level, stats);
+        }
+        return level;
+    }
+    /**
+     * Log memory warning with details.
+     * @param level
+     * @param stats
+     */
+    logWarning(level, stats) {
+        const levelColors = {
+            [MemoryWarningLevel.WARNING]: "\u001B[33m", // Yellow
+            [MemoryWarningLevel.CRITICAL]: "\u001B[31m", // Red
+            [MemoryWarningLevel.EMERGENCY]: "\u001B[35m", // Magenta
+            [MemoryWarningLevel.NORMAL]: "\u001B[32m", // Green
+        };
+        const reset = "\u001B[0m";
+        const color = levelColors[level];
+        console.warn(`${color}[Memory ${level.toUpperCase()}]${reset} ` +
+            `RSS: ${stats.rssMb.toFixed(1)}MB ` +
+            `| Heap: ${(stats.heapUsedBytes / 1024 / 1024).toFixed(1)}MB / ${(stats.heapTotalBytes / 1024 / 1024).toFixed(1)}MB ` +
+            `(${stats.heapUsagePercent.toFixed(1)}%)`);
+    }
+    /**
+     * Create a memory snapshot for provenance tracking.
+     */
+    snapshot() {
+        return this.getStats();
+    }
+    /**
+     * Format memory stats for logging.
+     * @param stats
+     */
+    format(stats) {
+        const current = stats ?? this.getStats();
+        return `RSS: ${current.rssMb.toFixed(1)}MB, Heap: ${(current.heapUsedBytes / 1024 / 1024).toFixed(1)}MB`;
+    }
+}
+/**
+ * Global memory monitor instance for convenience.
+ */
+let globalMonitor = null;
+/**
+ * Get or create the global memory monitor.
+ * @param config
+ */
+export const getGlobalMemoryMonitor = (config) => {
+    globalMonitor ??= new MemoryMonitor(config);
+    return globalMonitor;
+};
+/**
+ * Check memory usage using the global monitor.
+ */
+export const checkMemoryUsage = () => {
+    const monitor = getGlobalMemoryMonitor();
+    return monitor.check();
+};
+/**
+ * Get current memory stats using the global monitor.
+ */
+export const getMemoryStats = () => {
+    const monitor = getGlobalMemoryMonitor();
+    return monitor.getStats();
+};
+//# sourceMappingURL=memory-monitor.js.map

package/dist/executor/memory-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.js","sourceRoot":"","sources":["../../src/executor/memory-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AA+BtC;;GAEG;AACH,MAAM,CAAN,IAAY,kBAYX;AAZD,WAAY,kBAAkB;IAC7B,0CAA0C;IAC1C,uCAAiB,CAAA;IAEjB,yCAAyC;IACzC,yCAAmB,CAAA;IAEnB,kDAAkD;IAClD,2CAAqB,CAAA;IAErB,sCAAsC;IACtC,6CAAuB,CAAA;AACxB,CAAC,EAZW,kBAAkB,KAAlB,kBAAkB,QAY7B;AAsBD;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB;IACzD,kBAAkB,EAAE,IAAI,EAAE,MAAM;IAChC,mBAAmB,EAAE,IAAI,EAAE,MAAM;IACjC,oBAAoB,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,uBAAuB;IAChH,OAAO,EAAE,KAAK;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,aAAa;IACR,MAAM,CAAsB;IACrC,YAAY,GAAuB,kBAAkB,CAAC,MAAM,CAAC;IAC7D,SAAS,CAAS;IAE1B,YAAY,MAAqC;QAChD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,qBAAqB,EAAE,GAAG,MAAM,EAAE,CAAC;QACtD,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,QAAQ;QACP,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QAElC,4CAA4C;QAC5C,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC;QACzB,MAAM,KAAK,GAAG,QAAQ,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACvC,MAAM,cAAc,GAAG,GAAG,CAAC,SAAS,CAAC;QACrC,MAAM,aAAa,GAAG,GAAG,CAAC,QAAQ,CAAC;QACnC,MAAM,gBAAgB,GAAG,CAAC,aAAa,GAAG,cAAc,CAAC,GAAG,GAAG,CAAC;QAEhE,yCAAyC;QACzC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QACnD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;QAEhD,OAAO;YACN,QAAQ;YACR,cAAc;YACd,aAAa;YACb,aAAa,EAAE,GAAG,CAAC,QAAQ;YAC3B,iBAAiB,EAAE,GAAG,CAAC,YAAY;YACnC,KAAK;YACL,gBAAgB;YAChB,SAAS;SACT,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,KAAmB;QAClC,MAAM,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAEzC,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;YACvD,OAAO,kBAAkB,CAAC,SAAS,CAAC;QACrC,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;YACtD,OAAO,kBAAkB,CAAC,QAAQ,CAAC;QACpC,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YACrD,OAAO,kBAAkB,CAAC,OAAO,CAAC;QACnC,CAAC;QACD,OAAO,kBAAkB,CAAC,MAAM,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,KAAK;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAE1C,oCAAoC;QACpC,IAAI,KAAK,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;YAC1B,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;gBACtC,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAChD,CAAC;QACF,CAAC;QAED,yBAAyB;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,KAAK,KAAK,kBAAkB,CAAC,MAAM,EAAE,CAAC;YAChE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC;IAED;;;;OAIG;IACK,UAAU,CAAC,KAAyB,EAAE,KAAkB;QAC/D,MAAM,WAAW,GAAG;YACnB,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,SAAS;YACrD,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,MAAM;YACnD,CAAC,kBAAkB,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,UAAU;YACxD,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,QAAQ;SACnD,CAAC;QACF,MAAM,KAAK,GAAG,WAAW,CAAC;QAC1B,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QAEjC,OAAO,CAAC,IAAI,CACX,GAAG,KAAK,WAAW,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,GAAG;YACjD,QAAQ,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;YACnC,WAAW,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;YACrH,IAAI,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAC1C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ;QACP,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAmB;QACzB,MAAM,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzC,OAAO,QAAQ,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,aAAa,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1G,CAAC;CACD;AAED;;GAEG;AACH,IAAI,aAAa,GAAyB,IAAI,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAqC,EAAiB,EAAE;IAC9F,aAAa,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,aAAa,CAAC;AACtB,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAuB,EAAE;IACxD,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;IACzC,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAgB,EAAE;IAC/C,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;IACzC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC,CAAC"}

package/dist/executor/parallel-executor.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Parallel executor using child processes.
+ *
+ * Spawns multiple Node.js processes, each executing a subset of runs.
+ * Each worker writes to its own sharded checkpoint file to avoid race conditions.
+ *
+ * Sharded checkpoint files:
+ *   results/execute/checkpoint-worker-00.json
+ *   results/execute/checkpoint-worker-01.json
+ *   ...
+ *
+ * Dependency Injection:
+ * - Logger interface enables testing of log output
+ * - ProcessSpawner interface enables mocking spawn() calls
+ * - SystemInfo interface enables testing CPU count and node path logic
+ */
+import type { EvaluationResult } from "../types/result.js";
+import type { ExecutorConfig, PlannedRun } from "./executor.js";
+/**
+ * Logger interface for output handling.
+ * Enables testing of log messages.
+ */
+export interface ILogger {
+    log(message: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * Production logger using console.
+ */
+export declare class ConsoleLogger implements ILogger {
+    log(message: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * Spawn options matching child_process.spawn signature.
+ */
+export interface SpawnOptions {
+    cwd?: string;
+    stdio?: "inherit" | "pipe" | "ignore";
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Child process interface.
+ * Abstraction over Node.js ChildProcess.
+ */
+export interface IChildProcess {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+}
+/**
+ * Process spawner interface.
+ * Enables mocking of spawn() for testing.
+ */
+export interface IProcessSpawner {
+    spawn(command: string, args: string[], options: SpawnOptions): IChildProcess;
+}
+/**
+ * Production process spawner using node:child_process.
+ */
+export declare class ProcessSpawner implements IProcessSpawner {
+    spawn(command: string, args: string[], options: SpawnOptions): IChildProcess;
+}
+/**
+ * System information interface.
+ * Enables testing of CPU count and node path logic.
+ */
+export interface ISystemInfo {
+    /** Number of CPU cores available */
+    cpuCount: number;
+    /** Path to the Node.js executable */
+    nodePath: string;
+    /** Package root directory */
+    packageRoot: string;
+    /** Current process environment */
+    env: Record<string, string | undefined>;
+}
+/**
+ * Production system info using node:os and process.
+ */
+export declare class SystemInfo implements ISystemInfo {
+    cpuCount: number;
+    nodePath: string;
+    env: NodeJS.ProcessEnv;
+    readonly packageRoot: string;
+    constructor();
+    /**
+     * Get the package root directory by resolving from the entry point script.
+     * The CLI entry point is dist/cli.js, so we go up one level from there.
+     */
+    private getPackageRoot;
+}
+export interface ParallelExecutorOptions {
+    /** Number of parallel processes (default: CPU count) */
+    workers?: number;
+    /** Path to node executable */
+    nodePath?: string;
+    /** Checkpoint directory (defaults to "results/execute") */
+    checkpointDir?: string;
+    /** Per-run timeout in milliseconds (0 = no timeout) */
+    timeoutMs?: number;
+}
+/**
+ * Generate random worker names using tech-themed adjectives.
+ * Returns unique names for each worker.
+ * @param count
+ */
+export declare const generateWorkerNames: (count: number) => string[];
+/**
+ * Generate sharded checkpoint path for a worker.
+ *
+ * @param checkpointDir - Base checkpoint directory
+ * @param workerIndex - Worker index (0-based)
+ * @returns Path to the worker's checkpoint file
+ */
+export declare const shardPath: (checkpointDir: string, workerIndex: number) => string;
+/**
+ * Batch of runs for a worker.
+ */
+export interface RunBatch {
+    /** Batch index */
+    index: number;
+    /** Run IDs in this batch */
+    runIds: string[];
+    /** JSON filter string for CLI */
+    filter: string;
+    /** First run ID in batch */
+    firstRunId: string;
+    /** Last run ID in batch */
+    lastRunId: string;
+}
+/**
+ * Worker configuration.
+ */
+export interface WorkerConfig {
+    /** Worker index */
+    index: number;
+    /** Worker name */
+    name: string;
+    /** Checkpoint path for this worker */
+    checkpointPath: string;
+    /** CLI arguments */
+    arguments: string[];
+    /** Environment variables */
+    env: Record<string, string | undefined>;
+}
+/**
+ * Parallel executor class with dependency injection.
+ *
+ * Spawns multiple Node.js processes, each executing a subset of runs.
+ * Each worker writes to its own sharded checkpoint file to avoid race conditions.
+ */
+export declare class ParallelExecutor {
+    private readonly logger;
+    private readonly spawner;
+    private readonly systemInfo;
+    constructor(logger?: ILogger, spawner?: IProcessSpawner, systemInfo?: ISystemInfo);
+    /**
+     * Split runs into batches for parallel processing.
+     * @param runs - Runs to distribute
+     * @param numberWorkers - Number of worker processes
+     * @returns Array of run batches
+     */
+    _createBatches(runs: PlannedRun[], numberWorkers: number): RunBatch[];
+    /**
+     * Create worker configurations for all batches.
+     * @param batches - Run batches
+     * @param workerNames - Names for each worker
+     * @param cliPath - Path to CLI entry point
+     * @param checkpointDir - Base checkpoint directory
+     * @param timeoutMs - Per-run timeout in milliseconds
+     * @returns Array of worker configurations
+     */
+    _createWorkerConfigs(batches: RunBatch[], workerNames: string[], cliPath: string, checkpointDir: string, timeoutMs: number): WorkerConfig[];
+    /**
+     * Spawn worker processes for all configurations.
+     * @param workerConfigs - Worker configurations
+     * @param nodePath - Path to node executable
+     * @param packageRoot - Package root directory
+     * @returns Array of child processes
+     */
+    _spawnWorkers(workerConfigs: WorkerConfig[], nodePath: string, packageRoot: string): IChildProcess[];
+    /**
+     * Wait for all workers to complete.
+     * @param workers - Child processes
+     * @returns Promise that resolves when all workers exit
+     */
+    _waitForWorkers(workers: IChildProcess[]): Promise<number[]>;
+    /**
+     * Execute runs using multiple parallel processes.
+     *
+     * Each worker writes to its own sharded checkpoint file to avoid race conditions.
+     * After all workers complete, the main process should merge the shards.
+     *
+     * @param runs - Planned runs to execute
+     * @param suts - SUT definitions (not used directly, passed to workers)
+     * @param cases - Case definitions (not used directly, passed to workers)
+     * @param config - Executor configuration
+     * @param options - Parallel executor options
+     * @returns Execution results (empty - CLI will load from shards)
+     */
+    execute(runs: PlannedRun[], _suts: unknown, _cases: unknown[], config: ExecutorConfig & {
+        onResult?: (result: EvaluationResult) => void;
+    }, options?: ParallelExecutorOptions): Promise<{
+        results: EvaluationResult[];
+        errors: {
+            runId: string;
+            error: string;
+        }[];
+    }>;
+}
+/**
+ * Execute runs using multiple parallel processes.
+ *
+ * Each worker writes to its own sharded checkpoint file to avoid race conditions.
+ * After all workers complete, the main process should merge the shards.
+ *
+ * This is a convenience function that creates a ParallelExecutor with default dependencies.
+ * For testing or custom behavior, use the ParallelExecutor class directly.
+ *
+ * @param runs - Planned runs to execute
+ * @param suts - SUT definitions (not used directly, passed to workers)
+ * @param cases - Case definitions (not used directly, passed to workers)
+ * @param config - Executor configuration
+ * @param options - Parallel executor options
+ * @returns Execution results (empty - CLI will load from shards)
+ */
+export declare const executeParallel: (runs: PlannedRun[], suts: unknown, cases: unknown[], config: ExecutorConfig & {
+    onResult?: (result: EvaluationResult) => void;
+}, options?: ParallelExecutorOptions) => Promise<{
+    results: EvaluationResult[];
+    errors: {
+        runId: string;
+        error: string;
+    }[];
+}>;
+//# sourceMappingURL=parallel-executor.d.ts.map

package/dist/executor/parallel-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-executor.d.ts","sourceRoot":"","sources":["../../src/executor/parallel-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,OAAO;IACvB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI1B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAG3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAChE;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa,CAAC;CAC7E;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,eAAe;IACrD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa;CAG5E;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC7C,QAAQ,SAAiB;IACzB,QAAQ,SAAoB;IAC5B,GAAG,oBAAe;IAClB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;;IAM7B;;;OAGG;IACH,OAAO,CAAC,cAAc;CAiBtB;AAED,MAAM,WAAW,uBAAuB;IACvC,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,MAAM,EAqEzD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,eAAe,MAAM,EAAE,aAAa,MAAM,KAAG,MACkB,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IAEnB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IAEd,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IAEb,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IAEvB,oBAAoB;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;gBAE7B,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,WAAW;IAMjF;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,QAAQ,EAAE;IAqBrE;;;;;;;;OAQG;IACH,oBAAoB,CACnB,OAAO,EAAE,QAAQ,EAAE,EACnB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GACf,YAAY,EAAE;IAoCjB;;;;;;OAMG;IACH,aAAa,CACZ,aAAa,EAAE,YAAY,EAAE,EAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GACjB,aAAa,EAAE;IAclB;;;;OAIG;IACG,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAalE;;;;;;;;;;;;OAYG;IACG,OAAO,CACZ,IAAI,EAAE,UAAU,EAAE,EAClB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,EAAE,EACjB,MAAM,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAA;KAAE,EAC1E,OAAO,GAAE,uBAA4B,GACnC,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;QAAC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;CAsDvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAC3B,MAAM,UAAU,EAAE,EAClB,MAAM,OAAO,EACb,OAAO,OAAO,EAAE,EAChB,QAAQ,cAAc,GAAG;IAAE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAA;CAAE,EAC1E,UAAS,uBAA4B,KACnC,OAAO,CAAC;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAGrF,CAAC"}