ppef 1.0.0 → 1.0.1

package/dist/executor/__tests__/parallel-executor.unit.test.js

@@ -0,0 +1,203 @@
+/**
+ * Unit tests for ParallelExecutor
+ *
+ * Tests worker name generation, run batch distribution, and shard path generation.
+ */
+import { describe, it } from "node:test";
+import { strict as assert } from "node:assert";
+import { shardPath } from "../parallel-executor.js";
+describe("ParallelExecutor", () => {
+    describe("shardPath", () => {
+        it("should generate zero-padded worker indices", () => {
+            const path0 = shardPath("/tmp/checkpoints", 0);
+            const path1 = shardPath("/tmp/checkpoints", 1);
+            const path9 = shardPath("/tmp/checkpoints", 9);
+            const path10 = shardPath("/tmp/checkpoints", 10);
+            const path99 = shardPath("/tmp/checkpoints", 99);
+            const path100 = shardPath("/tmp/checkpoints", 100);
+            assert.ok(path0.includes("checkpoint-worker-00.json"));
+            assert.ok(path1.includes("checkpoint-worker-01.json"));
+            assert.ok(path9.includes("checkpoint-worker-09.json"));
+            assert.ok(path10.includes("checkpoint-worker-10.json"));
+            assert.ok(path99.includes("checkpoint-worker-99.json"));
+            assert.ok(path100.includes("checkpoint-worker-100.json"));
+        });
+        it("should include checkpoint directory in path", () => {
+            const path = shardPath("/my/checkpoint/dir", 5);
+            assert.ok(path.includes("/my/checkpoint/dir"));
+            assert.ok(path.includes("checkpoint-worker-05.json"));
+        });
+    });
+    describe("run batch distribution (conceptual)", () => {
+        /**
+         * The executeParallel function uses the following algorithm:
+         * 1. Calculate batch size = ceil(runs.length / numWorkers)
+         * 2. Split runs into batches using slice(i, i + batchSize)
+         *
+         * This test verifies the algorithm produces expected results.
+         */
+        it("should distribute runs evenly across workers", () => {
+            const runs = Array.from({ length: 100 }, (_, index) => ({
+                runId: `run${index}`,
+                sutId: "sut",
+                caseId: "case",
+                repetition: 0,
+                seed: index,
+            }));
+            const numberWorkers = 4;
+            const batchSize = Math.ceil(runs.length / numberWorkers); // 25
+            const batches = [];
+            for (let index = 0; index < runs.length; index += batchSize) {
+                batches.push(runs.slice(index, index + batchSize));
+            }
+            assert.strictEqual(batches.length, 4);
+            assert.strictEqual(batches[0].length, 25);
+            assert.strictEqual(batches[1].length, 25);
+            assert.strictEqual(batches[2].length, 25);
+            assert.strictEqual(batches[3].length, 25);
+        });
+        it("should handle uneven distribution", () => {
+            const runs = Array.from({ length: 10 }, (_, index) => ({
+                runId: `run${index}`,
+                sutId: "sut",
+                caseId: "case",
+                repetition: 0,
+                seed: index,
+            }));
+            const numberWorkers = 3;
+            const batchSize = Math.ceil(runs.length / numberWorkers); // 4
+            const batches = [];
+            for (let index = 0; index < runs.length; index += batchSize) {
+                batches.push(runs.slice(index, index + batchSize));
+            }
+            assert.strictEqual(batches.length, 3);
+            assert.strictEqual(batches[0].length, 4);
+            assert.strictEqual(batches[1].length, 4);
+            assert.strictEqual(batches[2].length, 2); // Last batch gets remainder
+        });
+        it("should handle single worker", () => {
+            const runs = Array.from({ length: 50 }, (_, index) => ({
+                runId: `run${index}`,
+                sutId: "sut",
+                caseId: "case",
+                repetition: 0,
+                seed: index,
+            }));
+            const numberWorkers = 1;
+            const batchSize = Math.ceil(runs.length / numberWorkers); // 50
+            const batches = [];
+            for (let index = 0; index < runs.length; index += batchSize) {
+                batches.push(runs.slice(index, index + batchSize));
+            }
+            assert.strictEqual(batches.length, 1);
+            assert.strictEqual(batches[0].length, 50);
+        });
+        it("should handle more workers than runs", () => {
+            const runs = [
+                { runId: "run0", sutId: "sut", caseId: "case", repetition: 0, seed: 0 },
+                { runId: "run1", sutId: "sut", caseId: "case", repetition: 0, seed: 1 },
+            ];
+            const numberWorkers = 5;
+            const batchSize = Math.ceil(runs.length / numberWorkers); // 1
+            const batches = [];
+            for (let index = 0; index < runs.length; index += batchSize) {
+                batches.push(runs.slice(index, index + batchSize));
+            }
+            // With batchSize=1, we get 2 batches (one per run)
+            // The last 3 workers would get empty batches in the actual implementation
+            assert.ok(batches.length >= 2);
+            assert.strictEqual(batches[0].length, 1);
+            assert.strictEqual(batches[1].length, 1);
+        });
+    });
+    describe("run filter generation (conceptual)", () => {
+        /**
+         * Each worker receives a run filter as a JSON array of run IDs.
+         * This test verifies the filter format.
+         */
+        it("should generate JSON array of run IDs for each batch", () => {
+            const runs = [
+                { runId: "alpha", sutId: "sut", caseId: "case", repetition: 0, seed: 0 },
+                { runId: "bravo", sutId: "sut", caseId: "case", repetition: 0, seed: 1 },
+                { runId: "charlie", sutId: "sut", caseId: "case", repetition: 0, seed: 2 },
+            ];
+            const numberWorkers = 2;
+            const batchSize = Math.ceil(runs.length / numberWorkers); // 2
+            const runFilters = [];
+            for (let index = 0; index < runs.length; index += batchSize) {
+                const batch = runs.slice(index, index + batchSize);
+                const runIds = new Set(batch.map((r) => r.runId));
+                runFilters.push(JSON.stringify([...runIds]));
+            }
+            assert.strictEqual(runFilters.length, 2);
+            const filter0 = JSON.parse(runFilters[0]);
+            const filter1 = JSON.parse(runFilters[1]);
+            assert.ok(filter0.includes("alpha"));
+            assert.ok(filter0.includes("bravo"));
+            assert.ok(filter1.includes("charlie"));
+        });
+    });
+    describe("worker names generation (conceptual)", () => {
+        /**
+         * Worker names follow the pattern: {adjective}-{noun}-{hex-suffix}
+         * This test verifies names are unique and well-formatted.
+         */
+        it("should generate unique worker names", () => {
+            // The actual implementation uses random adjectives, nouns, and hex suffix
+            // Here we verify the pattern is followed
+            const adjectives = ["swift", "nimble", "quick"];
+            const nouns = ["runner", "worker", "processor"];
+            const usedNames = new Set();
+            const names = [];
+            for (let index = 0; index < 10; index++) {
+                const adj = adjectives[index % adjectives.length];
+                const noun = nouns[index % nouns.length];
+                const suffix = index.toString(16).padStart(4, "0"); // Simulate hex suffix
+                const name = `${adj}-${noun}-${suffix}`;
+                // Verify uniqueness
+                assert.ok(!usedNames.has(name));
+                usedNames.add(name);
+                names.push(name);
+            }
+            assert.strictEqual(names.length, 10);
+            assert.strictEqual(new Set(names).size, 10); // All unique
+        });
+    });
+    describe("spawn arguments (conceptual)", () => {
+        /**
+         * Verify that workers are spawned with correct arguments.
+         */
+        it("should include checkpoint-path argument for each worker", () => {
+            const checkpointDir = "/tmp/checkpoints";
+            const workerIndex = 2;
+            const checkpointPath = shardPath(checkpointDir, workerIndex);
+            assert.ok(checkpointPath.includes("checkpoint-worker-02.json"));
+            assert.ok(checkpointPath.includes(checkpointDir));
+        });
+        it("should include worker-index in environment variables", () => {
+            const workerIndex = 3;
+            const environmentVariable = `GRAPHBOX_WORKER_INDEX=${workerIndex}`;
+            assert.strictEqual(environmentVariable, "GRAPHBOX_WORKER_INDEX=3");
+        });
+        it("should include total-workers in environment variables", () => {
+            const totalWorkers = 5;
+            const environmentVariable = `GRAPHBOX_TOTAL_WORKERS=${totalWorkers}`;
+            assert.strictEqual(environmentVariable, "GRAPHBOX_TOTAL_WORKERS=5");
+        });
+    });
+});
+describe("ParallelExecutorOptions", () => {
+    describe("defaults", () => {
+        it("should use default checkpoint directory when not specified", () => {
+            const options = {};
+            const checkpointDir = options.checkpointDir ?? "/default/path";
+            assert.strictEqual(checkpointDir, "/default/path");
+        });
+        it("should use custom checkpoint directory when specified", () => {
+            const options = { checkpointDir: "/custom/path" };
+            const checkpointDir = options.checkpointDir;
+            assert.strictEqual(checkpointDir, "/custom/path");
+        });
+    });
+});
+//# sourceMappingURL=parallel-executor.unit.test.js.map

package/dist/executor/__tests__/parallel-executor.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-executor.unit.test.js","sourceRoot":"","sources":["../../../src/executor/__tests__/parallel-executor.unit.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IACjC,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;QAC1B,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;YACrD,MAAM,KAAK,GAAG,SAAS,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;YAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;YAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,SAAS,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;YACjD,MAAM,MAAM,GAAG,SAAS,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;YACjD,MAAM,OAAO,GAAG,SAAS,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;YAEnD,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;YACvD,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;YACvD,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;YACvD,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;YACxD,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;YACxD,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;YACtD,MAAM,IAAI,GAAG,SAAS,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;YAChD,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAC/C,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,qCAAqC,EAAE,GAAG,EAAE;QACpD;;;;;;WAMG;QACH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;YACvD,MAAM,IAAI,GAAiB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;gBACrE,KAAK,EAAE,MAAM,KAAK,EAAE;gBACpB,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,MAAM;gBACd,UAAU,EAAE,CAAC;gBACb,IAAI,EAAE,KAAK;aACX,CAAC,CAAC,CAAC;YAEJ,MAAM,aAAa,GAAG,CAAC,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,KAAK;YAE/D,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC;YACpD,CAAC;YAED,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;YAC5C,MAAM,IAAI,GAAiB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;gBACpE,KAAK,EAAE,MAAM,KAAK,EAAE;gBACpB,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,MAAM;gBACd,UAAU,EAAE,CAAC;gBACb,IAAI,EAAE,KAAK;aACX,CAAC,CAAC,CAAC;YAEJ,MAAM,aAAa,GAAG,CAAC,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI;YAE9D,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC;YACpD,CAAC;YAED,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACzC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACzC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,4BAA4B;QACvE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;YACtC,MAAM,IAAI,GAAiB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;gBACpE,KAAK,EAAE,MAAM,KAAK,EAAE;gBACpB,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,MAAM;gBACd,UAAU,EAAE,CAAC;gBACb,IAAI,EAAE,KAAK;aACX,CAAC,CAAC,CAAC;YAEJ,MAAM,aAAa,GAAG,CAAC,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,KAAK;YAE/D,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC;YACpD,CAAC;YAED,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;YAC/C,MAAM,IAAI,GAAiB;gBAC1B,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;gBACvE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;aACvE,CAAC;YAEF,MAAM,aAAa,GAAG,CAAC,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI;YAE9D,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC;YACpD,CAAC;YAED,mDAAmD;YACnD,0EAA0E;YAC1E,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;YAC/B,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACzC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;QACnD;;;WAGG;QACH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC/D,MAAM,IAAI,GAAiB;gBAC1B,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;gBACxE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;gBACxE,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;aAC1E,CAAC;YAEF,MAAM,aAAa,GAAG,CAAC,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI;YAE9D,MAAM,UAAU,GAAa,EAAE,CAAC;YAChC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;gBACnD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;gBAClD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YAC9C,CAAC;YAED,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAEzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAa,CAAC;YACtD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAa,CAAC;YAEtD,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACrC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACrC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,sCAAsC,EAAE,GAAG,EAAE;QACrD;;;WAGG;QACH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;YAC9C,0EAA0E;YAC1E,yCAAyC;YAEzC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;YAEhD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;YACpC,MAAM,KAAK,GAAa,EAAE,CAAC;YAE3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC;gBACzC,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;gBAClD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;gBACzC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,sBAAsB;gBAC1E,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;gBAExC,oBAAoB;gBACpB,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;gBAChC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACpB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;YAED,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACrC,MAAM,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa;QAC3D,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;QAC7C;;WAEG;QACH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;YAClE,MAAM,aAAa,GAAG,kBAAkB,CAAC;YACzC,MAAM,WAAW,GAAG,CAAC,CAAC;YACtB,MAAM,cAAc,GAAG,SAAS,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;YAE7D,MAAM,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;YAChE,MAAM,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC/D,MAAM,WAAW,GAAG,CAAC,CAAC;YACtB,MAAM,mBAAmB,GAAG,yBAAyB,WAAW,EAAE,CAAC;YAEnE,MAAM,CAAC,WAAW,CAAC,mBAAmB,EAAE,yBAAyB,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;YAChE,MAAM,YAAY,GAAG,CAAC,CAAC;YACvB,MAAM,mBAAmB,GAAG,0BAA0B,YAAY,EAAE,CAAC;YAErE,MAAM,CAAC,WAAW,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACxC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;QACzB,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;YACrE,MAAM,OAAO,GAA+B,EAAE,CAAC;YAC/C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,eAAe,CAAC;YAE/D,MAAM,CAAC,WAAW,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;YAChE,MAAM,OAAO,GAAG,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;YAClD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;YAE5C,MAAM,CAAC,WAAW,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,231 @@
+/**
+ * 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 type { CaseDefinition } from "../types/case.js";
+import type { EvaluationResult } from "../types/result.js";
+import type { SutDefinition } from "../types/sut.js";
+import type { CheckpointStorage, Lock } from "./checkpoint-storage.js";
+import type { ExecutorConfig, PlannedRun } from "./executor.js";
+export type { CheckpointMode } from "./checkpoint-storage.js";
+export type { Lock } from "./checkpoint-storage.js";
+export { InMemoryLock } from "./checkpoint-storage.js";
+/**
+ * Checkpoint file format.
+ */
+export interface CheckpointData {
+    /** Hash of the execution configuration (SUTs, cases, config) */
+    configHash: string;
+    /** Timestamp when checkpoint was created */
+    createdAt: string;
+    /** Timestamp of last update */
+    updatedAt: string;
+    /** IDs of completed runs (for quick lookup) */
+    completedRunIds: string[];
+    /** Stored results by run ID */
+    results: Record<string, EvaluationResult>;
+    /** Total number of planned runs */
+    totalPlanned: number;
+    /** Git commit at checkpoint time (for reproducibility) */
+    gitCommit?: string;
+    /** Worker index (for sharded checkpoints) */
+    workerIndex?: number;
+    /** Total workers (for sharded checkpoints) */
+    totalWorkers?: number;
+}
+/**
+ * Checkpoint manager constructor options.
+ */
+export interface CheckpointManagerOptions {
+    /** Storage backend for checkpoint data */
+    storage: CheckpointStorage;
+    /** Concurrency lock for checkpoint saves */
+    lock?: Lock;
+    /** Worker identity for sharded mode */
+    workerIndex?: number;
+    /** Total number of workers in sharded mode */
+    totalWorkers?: number;
+    /** Base checkpoint path (for sharding) */
+    basePath?: string;
+}
+/**
+ * Checkpoint manager for resumable execution.
+ *
+ * Uses dependency injection for storage and lock.
+ * Enables sharded checkpoints for parallel worker execution.
+ */
+export declare class CheckpointManager {
+    private readonly storage;
+    private readonly lock;
+    private readonly workerIndex?;
+    private readonly totalWorkers?;
+    private readonly basePath?;
+    private data;
+    private dirty;
+    /**
+     * Create a new CheckpointManager.
+     *
+     * @param options - CheckpointManagerOptions with injected storage
+     */
+    constructor(options: CheckpointManagerOptions);
+    /**
+     * Get the storage backend being used.
+     */
+    getStorageType(): string;
+    /**
+     * Load checkpoint from storage if it exists.
+     * @returns true if checkpoint was loaded, false if not found or invalid
+     */
+    load(): Promise<boolean>;
+    /**
+     * Save checkpoint to storage.
+     */
+    save(): Promise<void>;
+    /**
+     * Save checkpoint incrementally (after each result).
+     * Uses the injected lock to prevent concurrent writes.
+     * @param result
+     */
+    saveIncremental(result: EvaluationResult): Promise<void>;
+    /**
+     * Check if checkpoint exists and is valid.
+     */
+    exists(): boolean;
+    /**
+     * Check if a specific run has been completed.
+     * @param runId - Run identifier
+     */
+    isCompleted(runId: string): boolean;
+    /**
+     * Get all completed results.
+     */
+    getResults(): EvaluationResult[];
+    /**
+     * Get progress information.
+     */
+    getProgress(): {
+        completed: number;
+        total: number;
+        percent: number;
+    };
+    /**
+     * 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<TExpander, TResult>(suts: SutDefinition<TExpander, TResult>[], cases: CaseDefinition<TExpander>[], config: Partial<ExecutorConfig>, totalRuns: number): boolean;
+    /**
+     * Invalidate checkpoint (delete and start fresh).
+     */
+    invalidate(): void;
+    /**
+     * Initialize empty checkpoint data.
+     * @param suts
+     * @param cases
+     * @param config
+     * @param totalRuns
+     * @param gitCommit
+     */
+    initializeEmpty<TExpander, TResult>(suts?: SutDefinition<TExpander, TResult>[], cases?: CaseDefinition<TExpander>[], config?: Partial<ExecutorConfig>, totalRuns?: number, gitCommit?: string): void;
+    /**
+     * Compute hash of execution configuration.
+     * Used to detect when configuration changes invalidate checkpoint.
+     * @param suts
+     * @param cases
+     * @param config
+     * @param totalRuns
+     */
+    private computeConfigHash;
+    /**
+     * Get remaining planned runs (excluding completed).
+     * @param plannedRuns - All planned runs
+     */
+    filterRemaining<T extends PlannedRun>(plannedRuns: T[]): T[];
+    /**
+     * Merge new results into checkpoint (for batch updates).
+     * @param results - New results to add
+     */
+    mergeResults(results: EvaluationResult[]): void;
+    /**
+     * 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
+     */
+    mergeShards(shardPaths: string[]): Promise<CheckpointData>;
+    /**
+     * Get checkpoint summary for logging.
+     */
+    getSummary(): string;
+}
+/**
+ * Get git commit hash for reproducibility.
+ */
+export declare const getGitCommit: () => Promise<string | 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 declare const createFileCheckpointManager: (path?: string, lock?: Lock) => CheckpointManager;
+//# sourceMappingURL=checkpoint-manager.d.ts.map

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

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