@crewhaus/branch-history 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 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;
+};
+export declare function branchAt(store: CheckpointStore, parentGraphRunId: GraphRunId, checkpointId: CheckpointId): Promise<BranchAtResult>;
+export declare function diff(store: CheckpointStore, graphRunIdA: GraphRunId, graphRunIdB: GraphRunId): Promise<ReadonlyArray<NodeDiff>>;

package/dist/index.js

@@ -0,0 +1,84 @@
+/**
+ * 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";
+function stateHash(c) {
+    // `JSON.stringify` returns `undefined` for `state === undefined` (and for
+    // values that serialize to nothing, e.g. functions/symbols). Feeding that
+    // straight into `createHash().update()` throws a TypeError, so coalesce to a
+    // stable sentinel — every other state serializes unchanged, preserving hashes.
+    const serialized = JSON.stringify(c.state) ?? "undefined";
+    return createHash("sha256").update(serialized).digest("hex").slice(0, 16);
+}
+export async function branchAt(store, parentGraphRunId, checkpointId) {
+    const result = await store.branch(parentGraphRunId, checkpointId);
+    return result;
+}
+export async function diff(store, graphRunIdA, graphRunIdB) {
+    const [a, b] = await Promise.all([store.list(graphRunIdA), store.list(graphRunIdB)]);
+    const out = [];
+    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;
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/branch-history",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Branch + diff helpers over checkpoint-store — time-travel utilities for the GRPH target",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/checkpoint-store": "0.1.3",
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/checkpoint-store": "0.1.5",
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,125 +0,0 @@
-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");
-  });
-
-  test("only-b reported when run B is longer than run A", async () => {
-    const a = newGraphRunId();
-    const b = newGraphRunId();
-    await store.save({ graphRunId: a, nodeName: "x", state: 0 });
-    await store.save({ graphRunId: b, nodeName: "x", state: 0 });
-    await new Promise((r) => setTimeout(r, 10));
-    const extra = await store.save({ graphRunId: b, nodeName: "y", state: 1 });
-    const d = await diff(store, a, b);
-    expect(d.length).toBe(2);
-    expect(d[0]?.kind).toBe("same");
-    expect(d[1]?.kind).toBe("only-b");
-    // The only-b row carries B's checkpoint metadata and no `a` side.
-    expect(d[1]?.a).toBeUndefined();
-    expect(d[1]?.b?.checkpointId).toBe(extra.id);
-    expect(d[1]?.b?.nodeName).toBe("y");
-    expect(typeof d[1]?.b?.stateHash).toBe("string");
-  });
-});
-
-describe("stateHash (via diff)", () => {
-  // Regression: a checkpoint whose `state` serializes to `undefined`
-  // (e.g. `state: undefined`) once crashed `diff` with a TypeError from
-  // `createHash().update(undefined)`. It must now hash to a stable sentinel.
-  test("checkpoints with undefined state diff without throwing", async () => {
-    const a = newGraphRunId();
-    const b = newGraphRunId();
-    await store.save({ graphRunId: a, nodeName: "x", state: undefined });
-    await store.save({ graphRunId: b, nodeName: "x", state: undefined });
-    const d = await diff(store, a, b);
-    expect(d.length).toBe(1);
-    // Two undefined states hash identically, so the row is `same`.
-    expect(d[0]?.kind).toBe("same");
-    expect(d[0]?.a?.stateHash).toBe(d[0]?.b?.stateHash);
-  });
-
-  test("undefined state differs from a defined state", async () => {
-    const a = newGraphRunId();
-    const b = newGraphRunId();
-    await store.save({ graphRunId: a, nodeName: "x", state: undefined });
-    await store.save({ graphRunId: b, nodeName: "x", state: { v: 1 } });
-    const d = await diff(store, a, b);
-    expect(d.length).toBe(1);
-    expect(d[0]?.kind).toBe("state-mismatch");
-    expect(d[0]?.a?.stateHash).not.toBe(d[0]?.b?.stateHash);
-  });
-});

package/src/index.ts

@@ -1,120 +0,0 @@
-/**
- * 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 {
-  // `JSON.stringify` returns `undefined` for `state === undefined` (and for
-  // values that serialize to nothing, e.g. functions/symbols). Feeding that
-  // straight into `createHash().update()` throws a TypeError, so coalesce to a
-  // stable sentinel — every other state serializes unchanged, preserving hashes.
-  const serialized = JSON.stringify(c.state) ?? "undefined";
-  return createHash("sha256").update(serialized).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;
-}