@smithers-orchestrator/time-travel 0.16.0

package/src/snapshot/SnapshotData.ts

@@ -0,0 +1,19 @@
+export type SnapshotData = {
+  nodes: Array<{
+    nodeId: string;
+    iteration: number;
+    state: string;
+    lastAttempt: number | null;
+    outputTable: string;
+    label: string | null;
+  }>;
+  outputs: Record<string, unknown>;
+  ralph: Array<{
+    ralphId: string;
+    iteration: number;
+    done: boolean;
+  }>;
+  input: Record<string, unknown>;
+  vcsPointer?: string | null;
+  workflowHash?: string | null;
+};

package/src/snapshot/captureSnapshotEffect.js

@@ -0,0 +1,70 @@
+import { Effect, Metric } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { createHash } from "node:crypto";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+import { smithersSnapshots } from "../schema.js";
+import { snapshotsCaptured } from "../snapshotsCaptured.js";
+import { snapshotDuration } from "../snapshotDuration.js";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("./Snapshot.ts").Snapshot} Snapshot */
+/** @typedef {import("./SnapshotData.ts").SnapshotData} SnapshotData */
+
+/**
+ * @param {SnapshotData} data
+ * @returns {string}
+ */
+function serializeSnapshotContent(data) {
+    return JSON.stringify({
+        nodes: data.nodes,
+        outputs: data.outputs,
+        ralph: data.ralph,
+        input: data.input,
+    });
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {SnapshotData} data
+ * @returns {Effect.Effect<Snapshot, SmithersError>}
+ */
+export function captureSnapshot(adapter, runId, frameNo, data) {
+    return Effect.gen(function* () {
+        const start = performance.now();
+        const nodesJson = JSON.stringify(data.nodes);
+        const outputsJson = JSON.stringify(data.outputs);
+        const ralphJson = JSON.stringify(data.ralph);
+        const inputJson = JSON.stringify(data.input);
+        const contentHash = createHash("sha256").update(serializeSnapshotContent(data)).digest("hex");
+        const ts = nowMs();
+        const row = {
+            runId,
+            frameNo,
+            nodesJson,
+            outputsJson,
+            ralphJson,
+            inputJson,
+            vcsPointer: data.vcsPointer ?? null,
+            workflowHash: data.workflowHash ?? null,
+            contentHash,
+            createdAtMs: ts,
+        };
+        yield* Effect.tryPromise({
+            try: () => adapter.db
+                .insert(smithersSnapshots)
+                .values(row)
+                .onConflictDoUpdate({
+                target: [smithersSnapshots.runId, smithersSnapshots.frameNo],
+                set: row,
+            }),
+            catch: (cause) => toSmithersError(cause, "insert snapshot", {
+                code: "DB_WRITE_FAILED",
+                details: { frameNo, runId },
+            }),
+        });
+        yield* Metric.increment(snapshotsCaptured);
+        yield* Metric.update(snapshotDuration, performance.now() - start);
+        return row;
+    }).pipe(Effect.annotateLogs({ runId, frameNo: String(frameNo) }), Effect.withLogSpan("time-travel:capture-snapshot"));
+}

package/src/snapshot/index.js

@@ -0,0 +1,57 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./Snapshot.ts").Snapshot} Snapshot */
+/** @typedef {import("./SnapshotData.ts").SnapshotData} SnapshotData */
+// @smithers-type-exports-end
+
+import { Effect } from "effect";
+import { captureSnapshot as captureSnapshotEffect } from "./captureSnapshotEffect.js";
+import { loadLatestSnapshot as loadLatestSnapshotEffect, loadSnapshot as loadSnapshotEffect, } from "./loadSnapshotEffect.js";
+import { listSnapshots as listSnapshotsEffect } from "./listSnapshotsEffect.js";
+export { parseSnapshot } from "./parseSnapshot.js";
+export { captureSnapshotEffect, listSnapshotsEffect, loadLatestSnapshotEffect, loadSnapshotEffect, };
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * Capture a snapshot row for a run at a given frame.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {SnapshotData} data
+ * @returns {Promise<Snapshot>}
+ */
+export function captureSnapshot(adapter, runId, frameNo, data) {
+    return Effect.runPromise(captureSnapshotEffect(adapter, runId, frameNo, data));
+}
+/**
+ * Load a specific snapshot row for a run/frame.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @returns {Promise<Snapshot | undefined>}
+ */
+export function loadSnapshot(adapter, runId, frameNo) {
+    return Effect.runPromise(loadSnapshotEffect(adapter, runId, frameNo));
+}
+/**
+ * Load the most recent snapshot row for a run.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Promise<Snapshot | undefined>}
+ */
+export function loadLatestSnapshot(adapter, runId) {
+    return Effect.runPromise(loadLatestSnapshotEffect(adapter, runId));
+}
+/**
+ * List lightweight snapshot index rows for a run.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Promise<Array<Pick<Snapshot, "runId" | "frameNo" | "contentHash" | "createdAtMs" | "vcsPointer">>>}
+ */
+export function listSnapshots(adapter, runId) {
+    return Effect.runPromise(listSnapshotsEffect(adapter, runId));
+}

package/src/snapshot/listSnapshotsEffect.js

@@ -0,0 +1,32 @@
+import { eq } from "drizzle-orm";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { smithersSnapshots } from "../schema.js";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("./Snapshot.ts").Snapshot} Snapshot */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Effect.Effect<Array<Pick<Snapshot, "runId" | "frameNo" | "contentHash" | "createdAtMs" | "vcsPointer">>, SmithersError>}
+ */
+export function listSnapshots(adapter, runId) {
+    return Effect.tryPromise({
+        try: () => adapter.db
+            .select({
+            runId: smithersSnapshots.runId,
+            frameNo: smithersSnapshots.frameNo,
+            contentHash: smithersSnapshots.contentHash,
+            createdAtMs: smithersSnapshots.createdAtMs,
+            vcsPointer: smithersSnapshots.vcsPointer,
+        })
+            .from(smithersSnapshots)
+            .where(eq(smithersSnapshots.runId, runId))
+            .orderBy(smithersSnapshots.frameNo),
+        catch: (cause) => toSmithersError(cause, "list snapshots", {
+            code: "DB_QUERY_FAILED",
+            details: { runId },
+        }),
+    }).pipe(Effect.annotateLogs({ runId }), Effect.withLogSpan("time-travel:list-snapshots"));
+}

package/src/snapshot/loadSnapshotEffect.js

@@ -0,0 +1,46 @@
+import { and, desc, eq } from "drizzle-orm";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { smithersSnapshots } from "../schema.js";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("./Snapshot.ts").Snapshot} Snapshot */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @returns {Effect.Effect<Snapshot | undefined, SmithersError>}
+ */
+export function loadSnapshot(adapter, runId, frameNo) {
+    return Effect.tryPromise({
+        try: () => adapter.db
+            .select()
+            .from(smithersSnapshots)
+            .where(and(eq(smithersSnapshots.runId, runId), eq(smithersSnapshots.frameNo, frameNo)))
+            .limit(1),
+        catch: (cause) => toSmithersError(cause, "load snapshot", {
+            code: "DB_QUERY_FAILED",
+            details: { frameNo, runId },
+        }),
+    }).pipe(Effect.map((rows) => rows[0]), Effect.annotateLogs({ runId, frameNo: String(frameNo) }), Effect.withLogSpan("time-travel:load-snapshot"));
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Effect.Effect<Snapshot | undefined, SmithersError>}
+ */
+export function loadLatestSnapshot(adapter, runId) {
+    return Effect.tryPromise({
+        try: () => adapter.db
+            .select()
+            .from(smithersSnapshots)
+            .where(eq(smithersSnapshots.runId, runId))
+            .orderBy(desc(smithersSnapshots.frameNo))
+            .limit(1),
+        catch: (cause) => toSmithersError(cause, "load latest snapshot", {
+            code: "DB_QUERY_FAILED",
+            details: { runId },
+        }),
+    }).pipe(Effect.map((rows) => rows[0]), Effect.annotateLogs({ runId }), Effect.withLogSpan("time-travel:load-latest-snapshot"));
+}

package/src/snapshot/parseSnapshot.js

@@ -0,0 +1,31 @@
+
+/** @typedef {import("../ParsedSnapshot.ts").ParsedSnapshot} ParsedSnapshot */
+/** @typedef {import("./Snapshot.ts").Snapshot} Snapshot */
+/**
+ * @param {Snapshot} snapshot
+ * @returns {ParsedSnapshot}
+ */
+export function parseSnapshot(snapshot) {
+    const nodesArr = JSON.parse(snapshot.nodesJson);
+    const nodes = {};
+    for (const n of nodesArr) {
+        nodes[`${n.nodeId}::${n.iteration}`] = n;
+    }
+    const ralphArr = JSON.parse(snapshot.ralphJson);
+    const ralph = {};
+    for (const r of ralphArr) {
+        ralph[r.ralphId] = r;
+    }
+    return {
+        runId: snapshot.runId,
+        frameNo: snapshot.frameNo,
+        nodes,
+        outputs: JSON.parse(snapshot.outputsJson),
+        ralph,
+        input: JSON.parse(snapshot.inputJson),
+        vcsPointer: snapshot.vcsPointer,
+        workflowHash: snapshot.workflowHash,
+        contentHash: snapshot.contentHash,
+        createdAtMs: snapshot.createdAtMs,
+    };
+}

package/src/snapshotDuration.js

@@ -0,0 +1,7 @@
+import { Metric, MetricBoundaries } from "effect";
+const snapshotBuckets = MetricBoundaries.exponential({
+    start: 1,
+    factor: 2,
+    count: 12,
+}); // ~1ms to ~2s
+export const snapshotDuration = Metric.histogram("smithers.snapshot.duration_ms", snapshotBuckets);

package/src/snapshotsCaptured.js

@@ -0,0 +1,2 @@
+import { Metric } from "effect";
+export const snapshotsCaptured = Metric.counter("smithers.snapshots.captured");

package/src/timeline/_helpers.js

@@ -0,0 +1,7 @@
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatTimestamp(ms) {
+    return new Date(ms).toISOString().replace("T", " ").replace(/\.\d+Z$/, "Z");
+}

package/src/timeline/buildTimelineEffect.js

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+import { listSnapshots } from "../snapshot/listSnapshotsEffect.js";
+import { listBranches } from "../fork/listBranchesEffect.js";
+import { getBranchInfo } from "../fork/getBranchInfoEffect.js";
+/** @typedef {import("../RunTimeline.ts").RunTimeline} RunTimeline */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Effect.Effect<RunTimeline, SmithersError>}
+ */
+export function buildTimeline(adapter, runId) {
+    return Effect.gen(function* () {
+        const snapshots = yield* listSnapshots(adapter, runId);
+        const branches = yield* listBranches(adapter, runId);
+        const ownBranch = yield* getBranchInfo(adapter, runId);
+        // Index branches by parent frame number for fast lookup
+        const branchByFrame = new Map();
+        for (const b of branches) {
+            const existing = branchByFrame.get(b.parentFrameNo) ?? [];
+            existing.push(b);
+            branchByFrame.set(b.parentFrameNo, existing);
+        }
+        const frames = snapshots.map((s) => ({
+            frameNo: s.frameNo,
+            createdAtMs: s.createdAtMs,
+            contentHash: s.contentHash,
+            forkPoints: branchByFrame.get(s.frameNo) ?? [],
+        }));
+        return {
+            runId,
+            frames,
+            branch: ownBranch ?? null,
+        };
+    }).pipe(Effect.annotateLogs({ runId }), Effect.withLogSpan("time-travel:build-timeline"));
+}

package/src/timeline/buildTimelineTreeEffect.js

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { buildTimeline } from "./buildTimelineEffect.js";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("../TimelineTree.ts").TimelineTree} TimelineTree */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Effect.Effect<TimelineTree, SmithersError>}
+ */
+export function buildTimelineTree(adapter, runId) {
+    return Effect.gen(function* () {
+        const timeline = yield* buildTimeline(adapter, runId);
+        // Collect all child runs that branch from this run
+        const childRunIds = [];
+        for (const frame of timeline.frames) {
+            for (const fork of frame.forkPoints) {
+                childRunIds.push(fork.runId);
+            }
+        }
+        // Recursively build subtrees
+        const children = [];
+        for (const childId of childRunIds) {
+            const childTree = yield* buildTimelineTree(adapter, childId);
+            children.push(childTree);
+        }
+        return { timeline, children };
+    }).pipe(Effect.annotateLogs({ runId }), Effect.withLogSpan("time-travel:build-timeline-tree"));
+}

package/src/timeline/formatTimelineAsJson.js

@@ -0,0 +1,23 @@
+
+/** @typedef {import("../TimelineTree.ts").TimelineTree} TimelineTree */
+/**
+ * @param {TimelineTree} tree
+ * @returns {object}
+ */
+export function formatTimelineAsJson(tree) {
+    return {
+        runId: tree.timeline.runId,
+        branch: tree.timeline.branch,
+        frames: tree.timeline.frames.map((f) => ({
+            frameNo: f.frameNo,
+            createdAtMs: f.createdAtMs,
+            contentHash: f.contentHash,
+            forks: f.forkPoints.map((fp) => ({
+                runId: fp.runId,
+                branchLabel: fp.branchLabel,
+                forkDescription: fp.forkDescription,
+            })),
+        })),
+        children: tree.children.map(formatTimelineAsJson),
+    };
+}

package/src/timeline/formatTimelineForTui.js

@@ -0,0 +1,31 @@
+import pc from "picocolors";
+import { formatTimestamp } from "./_helpers.js";
+/** @typedef {import("../TimelineTree.ts").TimelineTree} TimelineTree */
+
+/**
+ * @param {TimelineTree} tree
+ * @returns {string}
+ */
+export function formatTimelineForTui(tree, indent = 0) {
+    const lines = [];
+    const pad = "  ".repeat(indent);
+    const tl = tree.timeline;
+    const labelSuffix = tl.branch
+        ? ` ${pc.dim(`[${tl.branch.branchLabel ?? "fork"}]`)} ${pc.dim(`(forked from ${tl.branch.parentRunId.slice(0, 8)}:${tl.branch.parentFrameNo})`)}`
+        : "";
+    lines.push(`${pad}${pc.bold(tl.runId)}${labelSuffix}`);
+    for (const frame of tl.frames) {
+        const ts = formatTimestamp(frame.createdAtMs);
+        const hash = frame.contentHash.slice(0, 8);
+        lines.push(`${pad}  Frame ${frame.frameNo}  ${pc.dim(ts)}  ${pc.dim(hash)}`);
+        // Show fork points after the frame
+        for (const fork of frame.forkPoints) {
+            const childTree = tree.children.find((c) => c.timeline.runId === fork.runId);
+            if (childTree) {
+                lines.push(`${pad}  ${pc.yellow("|--")} ${pc.cyan(fork.runId.slice(0, 12))} ${pc.dim(`[${fork.branchLabel ?? "fork"}]`)} ${pc.dim(`(forked at frame ${fork.parentFrameNo})`)}`);
+                lines.push(formatTimelineForTui(childTree, indent + 2));
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/src/timeline/index.js

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import { buildTimeline as buildTimelineEffect } from "./buildTimelineEffect.js";
+import { buildTimelineTree as buildTimelineTreeEffect } from "./buildTimelineTreeEffect.js";
+export { formatTimelineForTui } from "./formatTimelineForTui.js";
+export { formatTimelineAsJson } from "./formatTimelineAsJson.js";
+export { buildTimelineEffect, buildTimelineTreeEffect, };
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("../RunTimeline.ts").RunTimeline} RunTimeline */
+/** @typedef {import("../TimelineTree.ts").TimelineTree} TimelineTree */
+
+/**
+ * Build the flat timeline (snapshots + branches) for a run.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Promise<RunTimeline>}
+ */
+export function buildTimeline(adapter, runId) {
+    return Effect.runPromise(buildTimelineEffect(adapter, runId));
+}
+/**
+ * Build the recursive timeline tree (run + all descendants) for a run.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Promise<TimelineTree>}
+ */
+export function buildTimelineTree(adapter, runId) {
+    return Effect.runPromise(buildTimelineTreeEffect(adapter, runId));
+}