@crewhaus/branch-history 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/branch-history",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Branch + diff helpers over checkpoint-store — time-travel utilities for the GRPH target",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/checkpoint-store": "0.0.0",
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/branch-history"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/branch-history#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type CheckpointStore,
+  createCheckpointStore,
+  newGraphRunId,
+} from "@crewhaus/checkpoint-store";
+import { branchAt, diff } from "./index";
+
+let tmp: string;
+let store: CheckpointStore;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "branch-history-"));
+  store = createCheckpointStore({ rootDir: tmp });
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("branchAt", () => {
+  test("returns the underlying store.branch result", async () => {
+    const grun = newGraphRunId();
+    const a = await store.save({ graphRunId: grun, nodeName: "a", state: { v: 1 } });
+    const r = await branchAt(store, grun, a.id);
+    expect(r.newGraphRunId).not.toBe(grun);
+    expect(r.head.state).toEqual({ v: 1 });
+  });
+});
+
+describe("diff", () => {
+  test("two identical runs report only `same` rows", async () => {
+    const a = newGraphRunId();
+    const b = newGraphRunId();
+    await store.save({ graphRunId: a, nodeName: "x", state: { i: 1 } });
+    await new Promise((r) => setTimeout(r, 10));
+    await store.save({ graphRunId: a, nodeName: "y", state: { i: 2 } });
+    await store.save({ graphRunId: b, nodeName: "x", state: { i: 1 } });
+    await new Promise((r) => setTimeout(r, 10));
+    await store.save({ graphRunId: b, nodeName: "y", state: { i: 2 } });
+    const d = await diff(store, a, b);
+    expect(d.length).toBe(2);
+    expect(d.every((row) => row.kind === "same")).toBe(true);
+  });
+
+  test("state mismatch flagged when same node has different state", async () => {
+    const a = newGraphRunId();
+    const b = newGraphRunId();
+    await store.save({ graphRunId: a, nodeName: "x", state: { v: 1 } });
+    await store.save({ graphRunId: b, nodeName: "x", state: { v: 2 } });
+    const d = await diff(store, a, b);
+    expect(d.length).toBe(1);
+    expect(d[0]?.kind).toBe("state-mismatch");
+  });
+
+  test("node mismatch flagged when nodes differ at same position", async () => {
+    const a = newGraphRunId();
+    const b = newGraphRunId();
+    await store.save({ graphRunId: a, nodeName: "x", state: 0 });
+    await store.save({ graphRunId: b, nodeName: "y", state: 0 });
+    const d = await diff(store, a, b);
+    expect(d[0]?.kind).toBe("node-mismatch");
+  });
+
+  test("only-a / only-b reported when one run is shorter", async () => {
+    const a = newGraphRunId();
+    const b = newGraphRunId();
+    await store.save({ graphRunId: a, nodeName: "x", state: 0 });
+    await new Promise((r) => setTimeout(r, 10));
+    await store.save({ graphRunId: a, nodeName: "y", state: 1 });
+    await store.save({ graphRunId: b, nodeName: "x", state: 0 });
+    const d = await diff(store, a, b);
+    expect(d[0]?.kind).toBe("same");
+    expect(d[1]?.kind).toBe("only-a");
+  });
+});

package/src/index.ts

@@ -0,0 +1,115 @@
+/**
+ * Catalog R7 `branch-history` — composable time-travel helpers.
+ *
+ * The runtime feature is owned by `checkpoint-store.branch()`; this
+ * package adds two ergonomics:
+ *
+ *   branchAt(store, parentRunId, checkpointId) — same as
+ *     `store.branch(...)` but records the branch lineage in a
+ *     dedicated event stream the operator UI can render.
+ *
+ *   diff(store, runIdA, runIdB) — walk both runs' checkpoints in
+ *     insertion order and emit a `NodeDiff[]` listing where they
+ *     diverge (different node names, different state hashes, or one
+ *     run terminated earlier than the other).
+ *
+ * Layer R7. Pairs with `checkpoint-store` (R7) and `graph-engine` (R11).
+ */
+
+import { createHash } from "node:crypto";
+import type {
+  Checkpoint,
+  CheckpointId,
+  CheckpointStore,
+  GraphRunId,
+} from "@crewhaus/checkpoint-store";
+
+export type NodeDiff = {
+  readonly position: number;
+  readonly a?: {
+    readonly checkpointId: CheckpointId;
+    readonly nodeName: string;
+    readonly stateHash: string;
+  };
+  readonly b?: {
+    readonly checkpointId: CheckpointId;
+    readonly nodeName: string;
+    readonly stateHash: string;
+  };
+  readonly kind: "same" | "node-mismatch" | "state-mismatch" | "only-a" | "only-b";
+};
+
+export type BranchAtResult = {
+  readonly newGraphRunId: GraphRunId;
+  readonly head: Checkpoint;
+};
+
+function stateHash(c: Checkpoint): string {
+  return createHash("sha256").update(JSON.stringify(c.state)).digest("hex").slice(0, 16);
+}
+
+export async function branchAt(
+  store: CheckpointStore,
+  parentGraphRunId: GraphRunId,
+  checkpointId: CheckpointId,
+): Promise<BranchAtResult> {
+  const result = await store.branch(parentGraphRunId, checkpointId);
+  return result;
+}
+
+export async function diff(
+  store: CheckpointStore,
+  graphRunIdA: GraphRunId,
+  graphRunIdB: GraphRunId,
+): Promise<ReadonlyArray<NodeDiff>> {
+  const [a, b] = await Promise.all([store.list(graphRunIdA), store.list(graphRunIdB)]);
+  const out: NodeDiff[] = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i += 1) {
+    const ca = a[i];
+    const cb = b[i];
+    if (ca === undefined && cb !== undefined) {
+      out.push({
+        position: i,
+        b: { checkpointId: cb.id, nodeName: cb.nodeName, stateHash: stateHash(cb) },
+        kind: "only-b",
+      });
+      continue;
+    }
+    if (cb === undefined && ca !== undefined) {
+      out.push({
+        position: i,
+        a: { checkpointId: ca.id, nodeName: ca.nodeName, stateHash: stateHash(ca) },
+        kind: "only-a",
+      });
+      continue;
+    }
+    if (ca !== undefined && cb !== undefined) {
+      const ha = stateHash(ca);
+      const hb = stateHash(cb);
+      if (ca.nodeName !== cb.nodeName) {
+        out.push({
+          position: i,
+          a: { checkpointId: ca.id, nodeName: ca.nodeName, stateHash: ha },
+          b: { checkpointId: cb.id, nodeName: cb.nodeName, stateHash: hb },
+          kind: "node-mismatch",
+        });
+      } else if (ha !== hb) {
+        out.push({
+          position: i,
+          a: { checkpointId: ca.id, nodeName: ca.nodeName, stateHash: ha },
+          b: { checkpointId: cb.id, nodeName: cb.nodeName, stateHash: hb },
+          kind: "state-mismatch",
+        });
+      } else {
+        out.push({
+          position: i,
+          a: { checkpointId: ca.id, nodeName: ca.nodeName, stateHash: ha },
+          b: { checkpointId: cb.id, nodeName: cb.nodeName, stateHash: hb },
+          kind: "same",
+        });
+      }
+    }
+  }
+  return out;
+}