@smithers-orchestrator/time-travel 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@smithers-orchestrator/time-travel",
+  "version": "0.16.0",
+  "description": "Smithers snapshots, diffs, forks, replay, timelines, and VCS-tagged run history",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./snapshot": {
+      "types": "./src/index.d.ts",
+      "import": "./src/snapshot/index.js",
+      "default": "./src/snapshot/index.js"
+    },
+    "./fork": {
+      "types": "./src/index.d.ts",
+      "import": "./src/fork/index.js",
+      "default": "./src/fork/index.js"
+    },
+    "./timeline": {
+      "types": "./src/index.d.ts",
+      "import": "./src/timeline/index.js",
+      "default": "./src/timeline/index.js"
+    },
+    "./vcs-version": {
+      "types": "./src/index.d.ts",
+      "import": "./src/vcs-version/index.js",
+      "default": "./src/vcs-version/index.js"
+    },
+    "./metrics": {
+      "types": "./src/index.d.ts",
+      "import": "./src/metrics.js",
+      "default": "./src/metrics.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@effect/platform-bun": "^0.89.0",
+    "drizzle-orm": "^0.45.1",
+    "picocolors": "^1.1.1",
+    "@smithers-orchestrator/driver": "0.16.0",
+    "@smithers-orchestrator/db": "0.16.0",
+    "@smithers-orchestrator/graph": "0.16.0",
+    "@smithers-orchestrator/scheduler": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/vcs": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/BranchInfo.ts

@@ -0,0 +1,11 @@
+/**
+ * Branch metadata.
+ */
+export type BranchInfo = {
+  runId: string;
+  parentRunId: string;
+  parentFrameNo: number;
+  branchLabel: string | null;
+  forkDescription: string | null;
+  createdAtMs: number;
+};

package/src/ForkParams.ts

@@ -0,0 +1,11 @@
+/**
+ * Parameters for forking a run.
+ */
+export type ForkParams = {
+  parentRunId: string;
+  frameNo: number;
+  inputOverrides?: Record<string, unknown>;
+  resetNodes?: string[];
+  branchLabel?: string;
+  forkDescription?: string;
+};

package/src/JUMP_MAX_FRAME_NO.js

@@ -0,0 +1 @@
+export const JUMP_MAX_FRAME_NO = 2_147_483_647;

package/src/JUMP_RUN_ID_PATTERN.js

@@ -0,0 +1 @@
+export const JUMP_RUN_ID_PATTERN = /^[a-z0-9_-]{1,64}$/;

package/src/JumpResult.ts

@@ -0,0 +1,9 @@
+export type JumpResult = {
+  ok: true;
+  newFrameNo: number;
+  revertedSandboxes: number;
+  deletedFrames: number;
+  deletedAttempts: number;
+  invalidatedDiffs: number;
+  durationMs: number;
+};

package/src/JumpStepName.ts

@@ -0,0 +1,10 @@
+export type JumpStepName =
+  | "snapshot-pre-jump"
+  | "pause-event-loop"
+  | "revert-sandboxes"
+  | "truncate-frames"
+  | "truncate-attempts"
+  | "truncate-outputs"
+  | "invalidate-diffs"
+  | "rebuild-reconciler"
+  | "resume-event-loop";

package/src/JumpToFrameError.js

@@ -0,0 +1,23 @@
+export class JumpToFrameError extends Error {
+  /** @type {string} */
+  code;
+
+  /** @type {string | undefined} */
+  hint;
+
+  /** @type {Record<string, unknown> | undefined} */
+  details;
+
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{ hint?: string; details?: Record<string, unknown> }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "JumpToFrameError";
+    this.code = code;
+    this.hint = options.hint;
+    this.details = options.details;
+  }
+}

package/src/JumpToFrameInput.ts

@@ -0,0 +1,36 @@
+import type { SmithersDb } from "@smithers-orchestrator/db/adapter";
+import type { SmithersEvent } from "@smithers-orchestrator/observability/SmithersEvent";
+import type { JumpStepName } from "./JumpStepName";
+
+export type JumpToFrameInput = {
+  adapter: SmithersDb;
+  runId: unknown;
+  frameNo: unknown;
+  confirm?: unknown;
+  caller?: string;
+  pauseRunLoop?: () => Promise<void> | void;
+  resumeRunLoop?: () => Promise<void> | void;
+  captureReconcilerState?: () => Promise<unknown> | unknown;
+  restoreReconcilerState?: (snapshot: unknown) => Promise<void> | void;
+  rebuildReconcilerState?: (xmlJson: string) => Promise<void> | void;
+  emitEvent?: (event: SmithersEvent) => Promise<void> | void;
+  getCurrentPointerImpl?: (cwd?: string) => Promise<string | null>;
+  revertToPointerImpl?: (
+    pointer: string,
+    cwd?: string,
+  ) => Promise<{ success: boolean; error?: string }>;
+  nowMs?: () => number;
+  rateLimit?: {
+    maxPerWindow?: number;
+    windowMs?: number;
+  };
+  hooks?: {
+    beforeStep?: (step: JumpStepName) => Promise<void> | void;
+    afterStep?: (step: JumpStepName) => Promise<void> | void;
+  };
+  onLog?: (
+    level: "info" | "warn" | "error",
+    message: string,
+    fields?: Record<string, unknown>,
+  ) => Promise<void> | void;
+};

package/src/NodeChange.ts

@@ -0,0 +1,7 @@
+import type { NodeSnapshot } from "./NodeSnapshot";
+
+export type NodeChange = {
+  nodeId: string;
+  from: NodeSnapshot;
+  to: NodeSnapshot;
+};

package/src/NodeSnapshot.ts

@@ -0,0 +1,8 @@
+export type NodeSnapshot = {
+  nodeId: string;
+  iteration: number;
+  state: string;
+  lastAttempt: number | null;
+  outputTable: string;
+  label: string | null;
+};

package/src/OutputChange.ts

@@ -0,0 +1,5 @@
+export type OutputChange = {
+  key: string;
+  from: unknown;
+  to: unknown;
+};

package/src/ParsedSnapshot.ts

@@ -0,0 +1,18 @@
+import type { NodeSnapshot } from "./NodeSnapshot";
+import type { RalphSnapshot } from "./RalphSnapshot";
+
+/**
+ * Parsed snapshot data for diffing and display.
+ */
+export type ParsedSnapshot = {
+  runId: string;
+  frameNo: number;
+  nodes: Record<string, NodeSnapshot>;
+  outputs: Record<string, unknown>;
+  ralph: Record<string, RalphSnapshot>;
+  input: Record<string, unknown>;
+  vcsPointer: string | null;
+  workflowHash: string | null;
+  contentHash: string;
+  createdAtMs: number;
+};

package/src/REWIND_RATE_LIMIT_MAX.js

@@ -0,0 +1 @@
+export const REWIND_RATE_LIMIT_MAX = 10;

package/src/REWIND_RATE_LIMIT_WINDOW_MS.js

@@ -0,0 +1 @@
+export const REWIND_RATE_LIMIT_WINDOW_MS = 60 * 60 * 1000;

package/src/RalphChange.ts

@@ -0,0 +1,7 @@
+import type { RalphSnapshot } from "./RalphSnapshot";
+
+export type RalphChange = {
+  ralphId: string;
+  from: RalphSnapshot;
+  to: RalphSnapshot;
+};

package/src/RalphSnapshot.ts

@@ -0,0 +1,5 @@
+export type RalphSnapshot = {
+  ralphId: string;
+  iteration: number;
+  done: boolean;
+};

package/src/ReplayParams.ts

@@ -0,0 +1,12 @@
+/**
+ * Parameters for replaying from a checkpoint.
+ */
+export type ReplayParams = {
+  parentRunId: string;
+  frameNo: number;
+  inputOverrides?: Record<string, unknown>;
+  resetNodes?: string[];
+  branchLabel?: string;
+  restoreVcs?: boolean;
+  cwd?: string;
+};

package/src/ReplayResult.ts

@@ -0,0 +1,11 @@
+import type { BranchInfo } from "./BranchInfo";
+import type { Snapshot } from "./snapshot/Snapshot";
+
+export type ReplayResult = {
+  runId: string;
+  branch: BranchInfo;
+  snapshot: Snapshot;
+  vcsRestored: boolean;
+  vcsPointer: string | null;
+  vcsError?: string;
+};

package/src/RetryTaskOptions.ts

@@ -0,0 +1,10 @@
+import type { SmithersEvent } from "@smithers-orchestrator/observability/SmithersEvent";
+
+export type RetryTaskOptions = {
+  runId: string;
+  nodeId: string;
+  iteration?: number;
+  resetDependents?: boolean;
+  force?: boolean;
+  onProgress?: (event: SmithersEvent) => void;
+};

package/src/RetryTaskResult.ts

@@ -0,0 +1,5 @@
+export type RetryTaskResult = {
+  success: boolean;
+  resetNodes: string[];
+  error?: string;
+};

package/src/RevertOptions.ts

@@ -0,0 +1,9 @@
+import type { SmithersEvent } from "@smithers-orchestrator/observability/SmithersEvent";
+
+export type RevertOptions = {
+  runId: string;
+  nodeId: string;
+  iteration: number;
+  attempt: number;
+  onProgress?: (event: SmithersEvent) => void;
+};

package/src/RevertResult.ts

@@ -0,0 +1,5 @@
+export type RevertResult = {
+  success: boolean;
+  error?: string;
+  jjPointer?: string;
+};

package/src/RewindAuditResult.ts

@@ -0,0 +1,5 @@
+export type RewindAuditResult =
+  | "success"
+  | "failed"
+  | "partial"
+  | "in_progress";

package/src/RewindLockHandle.ts

@@ -0,0 +1,4 @@
+export type RewindLockHandle = {
+  runId: string;
+  release: () => boolean;
+};

package/src/RunTimeline.ts

@@ -0,0 +1,11 @@
+import type { BranchInfo } from "./BranchInfo";
+import type { TimelineFrame } from "./TimelineFrame";
+
+/**
+ * Timeline for a single run.
+ */
+export type RunTimeline = {
+  runId: string;
+  frames: TimelineFrame[];
+  branch: BranchInfo | null;
+};

package/src/SnapshotDiff.ts

@@ -0,0 +1,18 @@
+import type { NodeChange } from "./NodeChange";
+import type { OutputChange } from "./OutputChange";
+import type { RalphChange } from "./RalphChange";
+
+/**
+ * Structured diff between two snapshots.
+ */
+export type SnapshotDiff = {
+  nodesAdded: string[];
+  nodesRemoved: string[];
+  nodesChanged: NodeChange[];
+  outputsAdded: string[];
+  outputsRemoved: string[];
+  outputsChanged: OutputChange[];
+  ralphChanged: RalphChange[];
+  inputChanged: boolean;
+  vcsPointerChanged: boolean;
+};

package/src/TimeTravelOptions.ts

@@ -0,0 +1,11 @@
+import type { SmithersEvent } from "@smithers-orchestrator/observability/SmithersEvent";
+
+export type TimeTravelOptions = {
+  runId: string;
+  nodeId: string;
+  iteration?: number;
+  attempt?: number;
+  resetDependents?: boolean;
+  restoreVcs?: boolean;
+  onProgress?: (event: SmithersEvent) => void;
+};

package/src/TimeTravelResult.ts

@@ -0,0 +1,7 @@
+export type TimeTravelResult = {
+  success: boolean;
+  jjPointer?: string;
+  vcsRestored: boolean;
+  resetNodes: string[];
+  error?: string;
+};

package/src/TimelineFrame.ts

@@ -0,0 +1,11 @@
+import type { BranchInfo } from "./BranchInfo";
+
+/**
+ * Timeline entry for a single frame in a run.
+ */
+export type TimelineFrame = {
+  frameNo: number;
+  createdAtMs: number;
+  contentHash: string;
+  forkPoints: BranchInfo[];
+};

package/src/TimelineTree.ts

@@ -0,0 +1,9 @@
+import type { RunTimeline } from "./RunTimeline";
+
+/**
+ * Recursive timeline tree including forks.
+ */
+export type TimelineTree = {
+  timeline: RunTimeline;
+  children: TimelineTree[];
+};

package/src/acquireRewindLock.js

@@ -0,0 +1,32 @@
+import { rewindLockStore } from "./rewindLockStore.js";
+
+/** @typedef {import("./RewindLockHandle.ts").RewindLockHandle} RewindLockHandle */
+
+/**
+ * Acquire a single-flight lock for one run.
+ * Returns null when another rewind for this run is already in progress.
+ *
+ * @param {string} runId
+ * @returns {RewindLockHandle | null}
+ */
+export function acquireRewindLock(runId) {
+  if (rewindLockStore.has(runId)) {
+    return null;
+  }
+  const token = Symbol(runId);
+  rewindLockStore.set(runId, token);
+  let released = false;
+  return {
+    runId,
+    release() {
+      if (released) {
+        return false;
+      }
+      released = true;
+      if (rewindLockStore.get(runId) === token) {
+        rewindLockStore.delete(runId);
+      }
+      return true;
+    },
+  };
+}

package/src/countRecentRewindAuditRows.js

@@ -0,0 +1,27 @@
+import { resolveRewindAuditClient } from "./resolveRewindAuditClient.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * Count audit rows for one caller and run in a time window.
+ * Only counts terminal (non-in_progress) rows so that a live attempt
+ * does not itself blow the rate-limit quota.
+ *
+ * @param {SmithersDb} adapter
+ * @param {{ runId: string; caller: string; sinceMs: number; }} input
+ * @returns {Promise<number>}
+ */
+export async function countRecentRewindAuditRows(adapter, input) {
+  const client = resolveRewindAuditClient(adapter);
+  const row = client
+    .query(
+      `SELECT COUNT(*) AS count
+         FROM _smithers_time_travel_audit
+        WHERE run_id = ?
+          AND caller = ?
+          AND timestamp_ms >= ?
+          AND result <> 'in_progress'`,
+    )
+    .get(input.runId, input.caller, input.sinceMs);
+  return Number(row?.count ?? 0);
+}

package/src/diff.js

@@ -0,0 +1,189 @@
+import pc from "picocolors";
+import { parseSnapshot } from "./snapshot/parseSnapshot.js";
+
+/** @typedef {import("./ParsedSnapshot.ts").ParsedSnapshot} ParsedSnapshot */
+/** @typedef {import("./snapshot/Snapshot.ts").Snapshot} Snapshot */
+/** @typedef {import("./SnapshotDiff.ts").SnapshotDiff} SnapshotDiff */
+
+// ---------------------------------------------------------------------------
+// Diffing — pure function, no DB access
+// ---------------------------------------------------------------------------
+/**
+ * Compute a structured diff between two parsed snapshots.
+ *
+ * @param {ParsedSnapshot} a
+ * @param {ParsedSnapshot} b
+ * @returns {SnapshotDiff}
+ */
+export function diffSnapshots(a, b) {
+    // Nodes
+    const aNodeKeys = new Set(Object.keys(a.nodes));
+    const bNodeKeys = new Set(Object.keys(b.nodes));
+    const nodesAdded = [];
+    const nodesRemoved = [];
+    const nodesChanged = [];
+    for (const key of bNodeKeys) {
+        if (!aNodeKeys.has(key)) {
+            nodesAdded.push(key);
+        }
+    }
+    for (const key of aNodeKeys) {
+        if (!bNodeKeys.has(key)) {
+            nodesRemoved.push(key);
+        }
+    }
+    for (const key of aNodeKeys) {
+        if (bNodeKeys.has(key)) {
+            const aNode = a.nodes[key];
+            const bNode = b.nodes[key];
+            if (aNode.state !== bNode.state ||
+                aNode.lastAttempt !== bNode.lastAttempt ||
+                aNode.label !== bNode.label) {
+                nodesChanged.push({ nodeId: key, from: aNode, to: bNode });
+            }
+        }
+    }
+    // Outputs
+    const aOutputKeys = new Set(Object.keys(a.outputs));
+    const bOutputKeys = new Set(Object.keys(b.outputs));
+    const outputsAdded = [];
+    const outputsRemoved = [];
+    const outputsChanged = [];
+    for (const key of bOutputKeys) {
+        if (!aOutputKeys.has(key)) {
+            outputsAdded.push(key);
+        }
+    }
+    for (const key of aOutputKeys) {
+        if (!bOutputKeys.has(key)) {
+            outputsRemoved.push(key);
+        }
+    }
+    for (const key of aOutputKeys) {
+        if (bOutputKeys.has(key)) {
+            const aVal = JSON.stringify(a.outputs[key]);
+            const bVal = JSON.stringify(b.outputs[key]);
+            if (aVal !== bVal) {
+                outputsChanged.push({ key, from: a.outputs[key], to: b.outputs[key] });
+            }
+        }
+    }
+    // Ralph
+    const ralphChanged = [];
+    const allRalphKeys = new Set([
+        ...Object.keys(a.ralph),
+        ...Object.keys(b.ralph),
+    ]);
+    for (const key of allRalphKeys) {
+        const aR = a.ralph[key];
+        const bR = b.ralph[key];
+        if (!aR || !bR) {
+            // One side missing — treat as changed if both exist
+            if (aR && bR) {
+                ralphChanged.push({ ralphId: key, from: aR, to: bR });
+            }
+            continue;
+        }
+        if (aR.iteration !== bR.iteration || aR.done !== bR.done) {
+            ralphChanged.push({ ralphId: key, from: aR, to: bR });
+        }
+    }
+    // Input
+    const inputChanged = JSON.stringify(a.input) !== JSON.stringify(b.input);
+    // VCS
+    const vcsPointerChanged = a.vcsPointer !== b.vcsPointer;
+    return {
+        nodesAdded,
+        nodesRemoved,
+        nodesChanged,
+        outputsAdded,
+        outputsRemoved,
+        outputsChanged,
+        ralphChanged,
+        inputChanged,
+        vcsPointerChanged,
+    };
+}
+/**
+ * Convenience: diff two raw Snapshot rows.
+ *
+ * @param {Snapshot} a
+ * @param {Snapshot} b
+ * @returns {SnapshotDiff}
+ */
+export function diffRawSnapshots(a, b) {
+    return diffSnapshots(parseSnapshot(a), parseSnapshot(b));
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/**
+ * Colorized terminal output for a snapshot diff.
+ *
+ * @param {SnapshotDiff} diff
+ * @returns {string}
+ */
+export function formatDiffForTui(diff) {
+    const lines = [];
+    if (diff.nodesAdded.length > 0) {
+        lines.push(pc.bold("Nodes added:"));
+        for (const n of diff.nodesAdded) {
+            lines.push(pc.green(`  + ${n}`));
+        }
+    }
+    if (diff.nodesRemoved.length > 0) {
+        lines.push(pc.bold("Nodes removed:"));
+        for (const n of diff.nodesRemoved) {
+            lines.push(pc.red(`  - ${n}`));
+        }
+    }
+    if (diff.nodesChanged.length > 0) {
+        lines.push(pc.bold("Nodes changed:"));
+        for (const c of diff.nodesChanged) {
+            lines.push(pc.yellow(`  ~ ${c.nodeId}: ${c.from.state} -> ${c.to.state}`));
+        }
+    }
+    if (diff.outputsAdded.length > 0) {
+        lines.push(pc.bold("Outputs added:"));
+        for (const o of diff.outputsAdded) {
+            lines.push(pc.green(`  + ${o}`));
+        }
+    }
+    if (diff.outputsRemoved.length > 0) {
+        lines.push(pc.bold("Outputs removed:"));
+        for (const o of diff.outputsRemoved) {
+            lines.push(pc.red(`  - ${o}`));
+        }
+    }
+    if (diff.outputsChanged.length > 0) {
+        lines.push(pc.bold("Outputs changed:"));
+        for (const o of diff.outputsChanged) {
+            lines.push(pc.yellow(`  ~ ${o.key}`));
+        }
+    }
+    if (diff.ralphChanged.length > 0) {
+        lines.push(pc.bold("Ralph (loops) changed:"));
+        for (const r of diff.ralphChanged) {
+            lines.push(pc.yellow(`  ~ ${r.ralphId}: iter ${r.from.iteration}->${r.to.iteration} done ${r.from.done}->${r.to.done}`));
+        }
+    }
+    if (diff.inputChanged) {
+        lines.push(pc.bold(pc.yellow("Input changed")));
+    }
+    if (diff.vcsPointerChanged) {
+        lines.push(pc.bold(pc.yellow("VCS pointer changed")));
+    }
+    if (lines.length === 0) {
+        lines.push(pc.dim("No differences"));
+    }
+    return lines.join("\n");
+}
+/**
+ * Structured JSON output for a snapshot diff.
+ *
+ * @param {SnapshotDiff} diff
+ * @returns {SnapshotDiff}
+ */
+export function formatDiffAsJson(diff) {
+    return { ...diff };
+}