ppef 1.0.0 → 1.0.1

package/dist/executor/checkpoint-manager.js

@@ -0,0 +1,395 @@
+/**
+ * Checkpoint Manager for Experiment Execution
+ *
+ * Enables resumable experiment execution by:
+ * 1. Writing incremental checkpoints after each completed run
+ * 2. Detecting configuration changes to invalidate stale checkpoints
+ * 3. Skipping completed runs when resuming
+ * 4. Supporting sharded checkpoints for parallel workers
+ *
+ * Supports pluggable storage backends:
+ * - FileStorage: JSON files (fast, local)
+ * - GitStorage: Git notes (version controlled, shareable)
+ *
+ * Dependency Injection:
+ * - Storage backend can be injected for testing
+ * - Lock implementation can be injected for custom concurrency control
+ *
+ * Usage:
+ * ```typescript
+ * // Direct instantiation with injected storage
+ * const storage = new FileStorage("results/execute/checkpoint.json");
+ * const lock = new InMemoryLock();
+ * const checkpoint = new CheckpointManager({ storage, lock });
+ *
+ * // Sharded mode for parallel workers
+ * const shardStorage = new FileStorage("results/execute/checkpoint-worker-0.json");
+ * const checkpoint = new CheckpointManager({
+ *   storage: shardStorage,
+ *   lock,
+ *   workerIndex: 0,
+ *   totalWorkers: 4,
+ *   basePath: "results/execute"
+ * });
+ *
+ * await checkpoint.load();
+ *
+ * if (checkpoint.isStale(suts, cases, config)) {
+ *   checkpoint.invalidate();
+ * }
+ *
+ * const remainingRuns = plannedRuns.filter(
+ *   run => !checkpoint.isCompleted(run.runId)
+ * );
+ *
+ * executor.execute({...}, {
+ *   onResult: (result) => checkpoint.saveIncremental(result)
+ * });
+ *
+ * // After all workers complete, merge shards
+ * await checkpoint.mergeShards([
+ *   "results/execute/checkpoint-worker-0.json",
+ *   "results/execute/checkpoint-worker-1.json",
+ *   ...
+ * ]);
+ * ```
+ */
+import { createHash } from "node:crypto";
+import { FileStorage, InMemoryLock } from "./checkpoint-storage.js";
+export { InMemoryLock } from "./checkpoint-storage.js";
+/**
+ * Checkpoint manager for resumable execution.
+ *
+ * Uses dependency injection for storage and lock.
+ * Enables sharded checkpoints for parallel worker execution.
+ */
+export class CheckpointManager {
+    storage;
+    lock;
+    workerIndex;
+    totalWorkers;
+    basePath;
+    data = null;
+    dirty = false;
+    /**
+     * Create a new CheckpointManager.
+     *
+     * @param options - CheckpointManagerOptions with injected storage
+     */
+    constructor(options) {
+        this.storage = options.storage;
+        this.lock = options.lock ?? new InMemoryLock();
+        this.workerIndex = options.workerIndex;
+        this.totalWorkers = options.totalWorkers;
+        this.basePath = options.basePath;
+    }
+    /**
+     * Get the storage backend being used.
+     */
+    getStorageType() {
+        return this.storage.type;
+    }
+    /**
+     * Load checkpoint from storage if it exists.
+     * @returns true if checkpoint was loaded, false if not found or invalid
+     */
+    async load() {
+        try {
+            const loaded = await this.storage.load();
+            if (loaded) {
+                this.data = loaded;
+                this.dirty = false;
+                return true;
+            }
+            this.data = null;
+            this.dirty = false;
+            return false;
+        }
+        catch {
+            this.data = null;
+            this.dirty = false;
+            return false;
+        }
+    }
+    /**
+     * Save checkpoint to storage.
+     */
+    async save() {
+        if (!this.dirty || !this.data) {
+            return;
+        }
+        try {
+            await this.storage.save(this.data);
+            this.dirty = false;
+        }
+        catch (error) {
+            console.warn(`Failed to save checkpoint: ${String(error)}`);
+        }
+    }
+    /**
+     * Save checkpoint incrementally (after each result).
+     * Uses the injected lock to prevent concurrent writes.
+     * @param result
+     */
+    async saveIncremental(result) {
+        // Acquire lock to prevent concurrent writes
+        await this.lock.acquire();
+        try {
+            // Always reload from file to get latest state (prevents stale memory corruption)
+            const currentData = await this.storage.load();
+            // Use loaded data or initialize if empty
+            const data = currentData ?? {
+                configHash: "pending",
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+                completedRunIds: [],
+                results: {},
+                totalPlanned: 0,
+                workerIndex: this.workerIndex,
+                totalWorkers: this.totalWorkers,
+            };
+            // Record the result (only if not already present)
+            if (!data.completedRunIds.includes(result.run.runId)) {
+                data.completedRunIds.push(result.run.runId);
+            }
+            data.results[result.run.runId] = result;
+            data.updatedAt = new Date().toISOString();
+            // Save immediately
+            await this.storage.save(data);
+        }
+        finally {
+            this.lock.release();
+        }
+    }
+    /**
+     * Check if checkpoint exists and is valid.
+     */
+    exists() {
+        return this.data !== null;
+    }
+    /**
+     * Check if a specific run has been completed.
+     * @param runId - Run identifier
+     */
+    isCompleted(runId) {
+        return this.data?.completedRunIds.includes(runId) ?? false;
+    }
+    /**
+     * Get all completed results.
+     */
+    getResults() {
+        if (!this.data) {
+            return [];
+        }
+        return Object.values(this.data.results);
+    }
+    /**
+     * Get progress information.
+     */
+    getProgress() {
+        if (!this.data) {
+            return { completed: 0, total: 0, percent: 0 };
+        }
+        const completed = this.data.completedRunIds.length;
+        const total = this.data.totalPlanned;
+        const percent = total > 0 ? (completed / total) * 100 : 0;
+        return { completed, total, percent: Math.round(percent) };
+    }
+    /**
+     * Check if checkpoint is stale (configuration has changed).
+     * @param suts - Current SUT definitions
+     * @param cases - Current case definitions
+     * @param config - Current executor config
+     * @param totalRuns - Total planned runs
+     */
+    isStale(suts, cases, config, totalRuns) {
+        if (!this.data) {
+            return false; // No checkpoint, not stale
+        }
+        const currentHash = this.computeConfigHash(suts, cases, config, totalRuns);
+        return this.data.configHash !== currentHash;
+    }
+    /**
+     * Invalidate checkpoint (delete and start fresh).
+     */
+    invalidate() {
+        this.data = null;
+        this.dirty = true;
+    }
+    /**
+     * Initialize empty checkpoint data.
+     * @param suts
+     * @param cases
+     * @param config
+     * @param totalRuns
+     * @param gitCommit
+     */
+    initializeEmpty(suts, cases, config, totalRuns, gitCommit) {
+        const configHash = suts && cases && config && totalRuns
+            ? this.computeConfigHash(suts, cases, config, totalRuns)
+            : "pending";
+        this.data = {
+            configHash,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            completedRunIds: [],
+            results: {},
+            totalPlanned: totalRuns ?? 0,
+            gitCommit,
+            workerIndex: this.workerIndex,
+            totalWorkers: this.totalWorkers,
+        };
+        this.dirty = true;
+    }
+    /**
+     * Compute hash of execution configuration.
+     * Used to detect when configuration changes invalidate checkpoint.
+     * @param suts
+     * @param cases
+     * @param config
+     * @param totalRuns
+     */
+    computeConfigHash(suts, cases, config, totalRuns) {
+        const signature = {
+            suts: suts.map((s) => ({
+                id: s.registration.id,
+                version: s.registration.version,
+            })),
+            cases: cases.map((c) => ({
+                id: c.case.caseId,
+                version: c.case.version ?? "1.0.0",
+            })),
+            executorConfig: {
+                repetitions: config.repetitions ?? 1,
+                seedBase: config.seedBase ?? 42,
+                timeoutMs: config.timeoutMs ?? 0,
+            },
+            totalRuns,
+        };
+        return createHash("sha256").update(JSON.stringify(signature)).digest("hex").slice(0, 16);
+    }
+    /**
+     * Get remaining planned runs (excluding completed).
+     * @param plannedRuns - All planned runs
+     */
+    filterRemaining(plannedRuns) {
+        if (!this.data) {
+            return plannedRuns;
+        }
+        const completedSet = new Set(this.data.completedRunIds);
+        return plannedRuns.filter((run) => !completedSet.has(run.runId));
+    }
+    /**
+     * Merge new results into checkpoint (for batch updates).
+     * @param results - New results to add
+     */
+    mergeResults(results) {
+        if (!this.data) {
+            this.initializeEmpty();
+        }
+        // Guard against null after initialization
+        if (!this.data) {
+            return;
+        }
+        for (const result of results) {
+            if (!this.data.completedRunIds.includes(result.run.runId)) {
+                this.data.completedRunIds.push(result.run.runId);
+                this.data.results[result.run.runId] = result;
+            }
+        }
+        this.dirty = true;
+    }
+    /**
+     * Merge multiple worker checkpoint shards into a single aggregated checkpoint.
+     *
+     * This is called after all parallel workers complete to aggregate their results.
+     * Each worker writes to its own shard file to avoid race conditions.
+     *
+     * @param shardPaths - Array of checkpoint shard file paths
+     * @returns The merged checkpoint data
+     */
+    async mergeShards(shardPaths) {
+        // Start with main checkpoint data, or empty if no checkpoint exists yet
+        const mainData = this.data;
+        const merged = {
+            configHash: mainData?.configHash ?? "",
+            createdAt: mainData?.createdAt ?? new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            completedRunIds: [...(mainData?.completedRunIds ?? [])],
+            results: { ...mainData?.results },
+            totalPlanned: mainData?.totalPlanned ?? 0,
+            gitCommit: mainData?.gitCommit,
+        };
+        // Load and merge each shard
+        for (const shardPath of shardPaths) {
+            const shardStorage = new FileStorage(shardPath);
+            const shardData = await shardStorage.load();
+            if (shardData) {
+                // Merge completed run IDs
+                merged.completedRunIds.push(...shardData.completedRunIds);
+                // Merge results
+                Object.assign(merged.results, shardData.results);
+                // Keep the maximum totalPlanned
+                if (shardData.totalPlanned > merged.totalPlanned) {
+                    merged.totalPlanned = shardData.totalPlanned;
+                }
+                // Keep the earliest createdAt
+                if (shardData.createdAt < merged.createdAt) {
+                    merged.createdAt = shardData.createdAt;
+                }
+                // Preserve config hash from first valid shard
+                if (merged.configHash === "" && shardData.configHash !== "pending") {
+                    merged.configHash = shardData.configHash;
+                }
+                // Preserve git commit if available
+                if (shardData.gitCommit && !merged.gitCommit) {
+                    merged.gitCommit = shardData.gitCommit;
+                }
+            }
+        }
+        // Deduplicate completedRunIds (in case of any overlap)
+        merged.completedRunIds = [...new Set(merged.completedRunIds)];
+        merged.updatedAt = new Date().toISOString();
+        // Save merged checkpoint
+        await this.storage.save(merged);
+        // Update internal state
+        this.data = merged;
+        this.dirty = false;
+        return merged;
+    }
+    /**
+     * Get checkpoint summary for logging.
+     */
+    getSummary() {
+        if (!this.data) {
+            return "No checkpoint";
+        }
+        const progress = this.getProgress();
+        return `Checkpoint: ${progress.completed}/${progress.total} runs (${progress.percent}%)`;
+    }
+}
+/**
+ * Get git commit hash for reproducibility.
+ */
+export const getGitCommit = async () => {
+    try {
+        const { execSync } = await import("node:child_process");
+        return execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Create a checkpoint manager with default file storage.
+ *
+ * Convenience factory for simple cases.
+ *
+ * @param path - Checkpoint file path
+ * @param lock - Optional lock implementation
+ */
+export const createFileCheckpointManager = (path = "results/execute/checkpoint.json", lock) => {
+    const storage = new FileStorage(path);
+    return new CheckpointManager({ storage, lock });
+};
+//# sourceMappingURL=checkpoint-manager.js.map

package/dist/executor/checkpoint-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.js","sourceRoot":"","sources":["../../src/executor/checkpoint-manager.ts"],"names":[],"mappings":"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"}

package/dist/executor/checkpoint-storage.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Checkpoint Storage Backends
+ *
+ * Pluggable storage for experiment checkpoints:
+ * - FileStorage: JSON files in local filesystem (fast, no git required)
+ * - GitStorage: Git notes attached to commits (version controlled, shareable)
+ *
+ * Dependency Injection:
+ * - FileSystem interface enables mocking for tests
+ * - Lock interface enables pluggable concurrency control
+ *
+ * Usage:
+ * ```typescript
+ * // File-based (default)
+ * const fileStorage = new FileStorage("results/execute/checkpoint.json");
+ *
+ * // Git-based (stores as git notes)
+ * const gitStorage = new GitStorage("results-execute");
+ *
+ * // With mock file system for testing
+ * const mockFs = new MockFileSystem();
+ * const fileStorage = new FileStorage("checkpoint.json", mockFs);
+ *
+ * // Auto-detect based on mode
+ * const storage = createCheckpointStorage("file", "results/execute/checkpoint.json");
+ * const storage = createCheckpointStorage("git", "results-execute");
+ * ```
+ */
+import type { CheckpointData } from "./checkpoint-manager.js";
+/**
+ * Interface for file system operations.
+ * Enables mocking for testing and alternative storage backends.
+ */
+export interface FileSystem {
+    /**
+     * Read file contents as UTF-8 string.
+     * @param path - Absolute file path
+     * @returns File contents or throws if not found
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Write string content to a file.
+     * @param path - Absolute file path
+     * @param content - Content to write
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Create directory recursively if it doesn't exist.
+     * @param path - Directory path
+     * @param options - Options including recursive flag
+     */
+    mkdir(path: string, options: {
+        recursive: boolean;
+    }): Promise<void>;
+    /**
+     * Delete a file if it exists.
+     * @param path - File path to delete
+     */
+    unlink(path: string): Promise<void>;
+    /**
+     * Check if file/directory exists.
+     * @param path - Path to check
+     */
+    access(path: string): Promise<void>;
+    /**
+     * List directory contents.
+     * @param path - Directory path
+     * @returns Array of entry names
+     */
+    readdir(path: string): Promise<string[]>;
+}
+/**
+ * Production file system implementation using node:fs/promises.
+ */
+export declare class NodeFileSystem implements FileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string, options: {
+        recursive: boolean;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    access(path: string): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+}
+/**
+ * Interface for concurrency control.
+ * Enables pluggable locking mechanisms for checkpoint saves.
+ */
+export interface Lock {
+    /**
+     * Acquire the lock, waiting if necessary.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release the lock.
+     */
+    release(): void;
+}
+/**
+ * In-memory lock for single-process use.
+ * Provides queue-based locking for concurrent saves within a process.
+ */
+export declare class InMemoryLock implements Lock {
+    private locked;
+    private queue;
+    acquire(): Promise<void>;
+    release(): void;
+}
+/**
+ * Checkpoint storage mode.
+ */
+export type CheckpointMode = "file" | "git" | "auto";
+/**
+ * Abstract checkpoint storage interface.
+ */
+export interface CheckpointStorage {
+    /**
+     * Load checkpoint data from storage.
+     * @returns Checkpoint data or null if not found
+     */
+    load(): CheckpointData | null | Promise<CheckpointData | null>;
+    /**
+     * Save checkpoint data to storage.
+     * @param data - Checkpoint data to save
+     */
+    save(data: CheckpointData): Promise<void>;
+    /**
+     * Delete checkpoint from storage.
+     */
+    delete(): void | Promise<void>;
+    /**
+     * Check if checkpoint exists.
+     */
+    exists(): boolean | Promise<boolean>;
+    /**
+     * Get storage type identifier.
+     */
+    readonly type: string;
+}
+/**
+ * File-based checkpoint storage.
+ * Stores checkpoints as JSON files in the local filesystem.
+ *
+ * Supports dependency injection of FileSystem for testing.
+ */
+export declare class FileStorage implements CheckpointStorage {
+    readonly type = "file";
+    private readonly path;
+    private readonly fs;
+    constructor(path: string, fs?: FileSystem);
+    load(): Promise<CheckpointData | null>;
+    save(data: CheckpointData): Promise<void>;
+    delete(): Promise<void>;
+    exists(): Promise<boolean>;
+    getPath(): string;
+    /**
+     * Find all worker checkpoint shard files in a directory.
+     * Looks for files matching the pattern "checkpoint-worker-*.json".
+     *
+     * @param baseDir - Directory to search for shard files
+     * @param fs - FileSystem implementation (defaults to NodeFileSystem)
+     * @returns Sorted array of shard file paths
+     */
+    static findShards(baseDir: string, fs?: FileSystem): Promise<string[]>;
+    /**
+     * Generate a shard file path for a specific worker.
+     *
+     * @param baseDir - Base directory for checkpoints
+     * @param workerIndex - Worker index (0-based)
+     * @returns Path to the shard checkpoint file
+     */
+    static shardPath(baseDir: string, workerIndex: number): string;
+}
+/**
+ * Git-based checkpoint storage using git notes.
+ *
+ * Checkpoints are stored as git notes attached to the current HEAD.
+ * This provides:
+ * - Version control: Checkpoints tracked in git history
+ * - Shareability: Team members can access each other's checkpoints
+ * - Reproducibility: Linked to specific commits
+ * - Safety: No accidental deletion through git clean
+ *
+ * Each checkpoint is stored as a note with a unique ref based on the namespace.
+ */
+export declare class GitStorage implements CheckpointStorage {
+    readonly type = "git";
+    private readonly namespace;
+    private readonly repoRoot;
+    constructor(namespace: string, repoRoot?: string);
+    /**
+     * Get the full notes ref for this checkpoint.
+     */
+    private getNotesRef;
+    /**
+     * Check if git is available and we're in a git repo.
+     */
+    private checkGitAvailable;
+    load(): CheckpointData | null;
+    save(data: CheckpointData): Promise<void>;
+    delete(): void;
+    exists(): boolean;
+    /**
+     * List all checkpoints for this namespace across git history.
+     * Returns a map of commit SHA to checkpoint metadata.
+     */
+    listHistory(): {
+        commit: string;
+        checkpoint: CheckpointData;
+    }[];
+    /**
+     * Restore checkpoint from a specific commit.
+     * @param commitSha
+     */
+    restoreFromCommit(commitSha: string): CheckpointData | null;
+}
+/**
+ * Create a checkpoint storage instance based on mode.
+ * @param mode - Storage mode ("file", "git", or "auto")
+ * @param pathOrNamespace - File path or git namespace
+ * @param repoRoot - Git repository root (for git storage)
+ */
+export declare const createCheckpointStorage: (mode: CheckpointMode, pathOrNamespace: string, repoRoot?: string) => CheckpointStorage;
+/**
+ * Get default checkpoint namespace for git storage.
+ * Based on results directory path.
+ * @param resultsDir
+ */
+export declare const getGitNamespace: (resultsDir: string) => string;
+//# sourceMappingURL=checkpoint-storage.d.ts.map

package/dist/executor/checkpoint-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-storage.d.ts","sourceRoot":"","sources":["../../src/executor/checkpoint-storage.ts"],"names":[],"mappings":"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"}