@crewhaus/durable-execution 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/durable-execution",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Exactly-once node execution wrapper over graph-engine — idempotency keys + crash-replay",
   "main": "src/index.ts",
@@ -12,14 +12,14 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/checkpoint-store": "0.0.0",
-    "@crewhaus/errors": "0.0.0"
+    "@crewhaus/checkpoint-store": "0.1.2",
+    "@crewhaus/errors": "0.1.2"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -31,12 +31,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -7,7 +7,14 @@ import {
   createCheckpointStore,
   newGraphRunId,
 } from "@crewhaus/checkpoint-store";
-import { idempotencyKey, resumeFrom, withIdempotency } from "./index";
+import {
+  type IdempotencyRecord,
+  type IdempotencyStore,
+  InMemoryIdempotencyStore,
+  idempotencyKey,
+  resumeFrom,
+  withIdempotency,
+} from "./index";
 
 let tmp: string;
 let store: CheckpointStore;
@@ -69,6 +76,120 @@ describe("withIdempotency", () => {
     await w1(grun, "n", { x: 0 });
     expect(invocations).toBe(2);
   });
+
+  test("honours an injected store and persists a well-formed record", async () => {
+    const grun = newGraphRunId();
+    const store = new InMemoryIdempotencyStore();
+    const wrapped = withIdempotency<{ v: number }>(async () => ({ v: 7 }), { store, attempt: 3 });
+    const out = await wrapped(grun, "node-z", { v: 0 });
+    expect(out).toEqual({ v: 7 });
+    // The record must be findable in the *shared* store under the derived key.
+    const rec = await store.get(idempotencyKey(grun, "node-z", 3));
+    expect(rec).toBeDefined();
+    expect(rec?.graphRunId).toBe(grun);
+    expect(rec?.nodeName).toBe("node-z");
+    expect(rec?.attempt).toBe(3);
+    expect(rec?.result).toEqual({ v: 7 });
+    // completedAt is a valid ISO-8601 timestamp.
+    expect(Number.isNaN(Date.parse(rec?.completedAt ?? ""))).toBe(false);
+  });
+
+  test("a second wrapper sharing the store reads the cached result", async () => {
+    const grun = newGraphRunId();
+    const store = new InMemoryIdempotencyStore();
+    let firstCalls = 0;
+    let secondCalls = 0;
+    const first = withIdempotency<{ v: number }>(
+      async () => {
+        firstCalls += 1;
+        return { v: 1 };
+      },
+      { store },
+    );
+    const second = withIdempotency<{ v: number }>(
+      async () => {
+        secondCalls += 1;
+        return { v: 2 };
+      },
+      { store },
+    );
+    const a = await first(grun, "shared", { v: 0 });
+    const b = await second(grun, "shared", { v: 0 });
+    expect(a).toEqual({ v: 1 });
+    // Cache hit: the second wrapper never runs its inner fn.
+    expect(b).toEqual({ v: 1 });
+    expect(firstCalls).toBe(1);
+    expect(secondCalls).toBe(0);
+  });
+
+  test("works with a custom IdempotencyStore implementation", async () => {
+    const grun = newGraphRunId();
+    const backing = new Map<string, IdempotencyRecord>();
+    const calls = { get: 0, put: 0 };
+    const custom: IdempotencyStore = {
+      async get(key) {
+        calls.get += 1;
+        return backing.get(key);
+      },
+      async put(record) {
+        calls.put += 1;
+        backing.set(record.key, record);
+      },
+    };
+    let invocations = 0;
+    const wrapped = withIdempotency<{ n: number }>(
+      async () => {
+        invocations += 1;
+        return { n: invocations };
+      },
+      { store: custom },
+    );
+    const a = await wrapped(grun, "node-c", { n: 0 });
+    const b = await wrapped(grun, "node-c", { n: 0 });
+    expect(a).toEqual({ n: 1 });
+    expect(b).toEqual({ n: 1 });
+    expect(invocations).toBe(1);
+    expect(calls.put).toBe(1);
+    expect(calls.get).toBe(2);
+  });
+});
+
+describe("InMemoryIdempotencyStore", () => {
+  test("get returns undefined for an absent key", async () => {
+    const store = new InMemoryIdempotencyStore();
+    expect(await store.get("does-not-exist")).toBeUndefined();
+  });
+
+  test("put then get round-trips the record", async () => {
+    const store = new InMemoryIdempotencyStore();
+    const grun = newGraphRunId();
+    const record: IdempotencyRecord = {
+      key: idempotencyKey(grun, "n", 0),
+      graphRunId: grun,
+      nodeName: "n",
+      attempt: 0,
+      result: { ok: true },
+      completedAt: new Date(0).toISOString(),
+    };
+    await store.put(record);
+    expect(await store.get(record.key)).toEqual(record);
+  });
+
+  test("put overwrites an existing record for the same key", async () => {
+    const store = new InMemoryIdempotencyStore();
+    const grun = newGraphRunId();
+    const key = idempotencyKey(grun, "n", 0);
+    const base = {
+      key,
+      graphRunId: grun,
+      nodeName: "n",
+      attempt: 0,
+      completedAt: new Date(0).toISOString(),
+    };
+    await store.put({ ...base, result: { v: 1 } });
+    await store.put({ ...base, result: { v: 2 } });
+    expect((await store.get(key))?.result).toEqual({ v: 2 });
+  });
 });
 
 describe("resumeFrom", () => {
@@ -85,4 +206,44 @@ describe("resumeFrom", () => {
     const grun = newGraphRunId();
     expect(await resumeFrom(store, grun)).toBeUndefined();
   });
+
+  test("returns undefined when meta exists but has no head", async () => {
+    const grun = newGraphRunId();
+    // A freshly-branched run can have meta with `head` absent (see
+    // checkpoint-store GraphRunMeta docs). Model it directly via a stub so
+    // the test is deterministic and does not depend on branch internals.
+    const stub = {
+      async meta() {
+        return { version: 1 as const, graphRunId: grun, createdAt: new Date(0).toISOString() };
+      },
+      async load() {
+        throw new Error("load must not be called when head is undefined");
+      },
+    } as unknown as CheckpointStore;
+    expect(await resumeFrom(stub, grun)).toBeUndefined();
+  });
+
+  test("returns undefined when head checkpoint is missing", async () => {
+    const grun = newGraphRunId();
+    // meta names a head, but the underlying checkpoint cannot be loaded
+    // (e.g. a corrupted/partially-deleted store). resumeFrom must fail
+    // safe rather than dereference an undefined checkpoint.
+    let loadCalls = 0;
+    const stub = {
+      async meta() {
+        return {
+          version: 1 as const,
+          graphRunId: grun,
+          head: "ckpt_00000000000000aa",
+          createdAt: new Date(0).toISOString(),
+        };
+      },
+      async load() {
+        loadCalls += 1;
+        return undefined;
+      },
+    } as unknown as CheckpointStore;
+    expect(await resumeFrom(stub, grun)).toBeUndefined();
+    expect(loadCalls).toBe(1);
+  });
 });

package/src/index.ts

@@ -54,7 +54,10 @@ export interface IdempotencyStore {
 }
 
 class InMemoryIdempotencyStore implements IdempotencyStore {
-  private readonly entries = new Map<IdempotencyKey, IdempotencyRecord>();
+  private readonly entries: Map<IdempotencyKey, IdempotencyRecord>;
+  constructor() {
+    this.entries = new Map<IdempotencyKey, IdempotencyRecord>();
+  }
   async get(key: IdempotencyKey): Promise<IdempotencyRecord | undefined> {
     return this.entries.get(key);
   }