@smithers-orchestrator/time-travel 0.16.0

package/src/listRewindAuditRows.js

@@ -0,0 +1,83 @@
+import { resolveRewindAuditClient } from "./resolveRewindAuditClient.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("./RewindAuditResult.ts").RewindAuditResult} RewindAuditResult */
+
+/**
+ * @typedef {{
+ *   id: number;
+ *   runId: string;
+ *   fromFrameNo: number;
+ *   toFrameNo: number;
+ *   caller: string;
+ *   timestampMs: number;
+ *   result: RewindAuditResult;
+ *   durationMs: number | null;
+ * }} RewindAuditRow
+ */
+
+/**
+ * @param {Array<Record<string, unknown>>} rows
+ * @returns {Array<RewindAuditRow>}
+ */
+function mapRewindAuditRows(rows) {
+  return rows.map((row) => ({
+    id: Number(row.id),
+    runId: String(row.runId),
+    fromFrameNo: Number(row.fromFrameNo),
+    toFrameNo: Number(row.toFrameNo),
+    caller: String(row.caller),
+    timestampMs: Number(row.timestampMs),
+    result: /** @type {RewindAuditResult} */ (String(row.result)),
+    durationMs: row.durationMs == null ? null : Number(row.durationMs),
+  }));
+}
+
+/**
+ * Fetch audit rows for tests and diagnostics.
+ *
+ * @param {SmithersDb} adapter
+ * @param {{ runId?: string; limit?: number; }} [input]
+ * @returns {Promise<Array<RewindAuditRow>>}
+ */
+export async function listRewindAuditRows(adapter, input = {}) {
+  const client = resolveRewindAuditClient(adapter);
+  const limit = Number.isInteger(input.limit) ? Math.max(1, Number(input.limit)) : 100;
+  if (typeof input.runId === "string") {
+    const rows = client
+      .query(
+        `SELECT
+             id,
+             run_id AS runId,
+             from_frame_no AS fromFrameNo,
+             to_frame_no AS toFrameNo,
+             caller,
+             timestamp_ms AS timestampMs,
+             result,
+             duration_ms AS durationMs
+           FROM _smithers_time_travel_audit
+           WHERE run_id = ?
+           ORDER BY id ASC
+           LIMIT ?`,
+      )
+      .all(input.runId, limit);
+    return mapRewindAuditRows(rows);
+  }
+  const rows = client
+    .query(
+      `SELECT
+           id,
+           run_id AS runId,
+           from_frame_no AS fromFrameNo,
+           to_frame_no AS toFrameNo,
+           caller,
+           timestamp_ms AS timestampMs,
+           result,
+           duration_ms AS durationMs
+         FROM _smithers_time_travel_audit
+         ORDER BY id ASC
+         LIMIT ?`,
+    )
+    .all(limit);
+  return mapRewindAuditRows(rows);
+}

package/src/metrics.js

@@ -0,0 +1,4 @@
+export { replaysStarted } from "./replaysStarted.js";
+export { runForksCreated } from "./runForksCreated.js";
+export { snapshotDuration } from "./snapshotDuration.js";
+export { snapshotsCaptured } from "./snapshotsCaptured.js";

package/src/recoverInProgressRewindAudits.js

@@ -0,0 +1,72 @@
+import { resolveRewindAuditClient } from "./resolveRewindAuditClient.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * On startup, find rewind audit rows left in `in_progress` by a prior crash,
+ * mark them as `partial`, and flag the associated runs as `needs_attention`.
+ *
+ * @param {SmithersDb} adapter
+ * @param {{ nowMs?: () => number }} [options]
+ * @returns {Promise<{ recovered: Array<{ id: number; runId: string }> }>}
+ */
+export async function recoverInProgressRewindAudits(adapter, options = {}) {
+  const nowMs = options.nowMs ?? (() => Date.now());
+  const client = resolveRewindAuditClient(adapter);
+  const rows = /** @type {Array<{ id: number; runId: string; timestampMs: number }>} */ (
+    client
+      .query(
+        `SELECT id, run_id AS runId, timestamp_ms AS timestampMs
+           FROM _smithers_time_travel_audit
+          WHERE result = 'in_progress'`,
+      )
+      .all()
+  );
+  if (rows.length === 0) {
+    return { recovered: [] };
+  }
+  const now = nowMs();
+  const updateStmt = client.query(
+    `UPDATE _smithers_time_travel_audit
+        SET result = 'partial',
+            duration_ms = COALESCE(duration_ms, ?)
+      WHERE id = ?`,
+  );
+  const recovered = [];
+  for (const row of rows) {
+    const duration = Math.max(0, now - Number(row.timestampMs ?? now));
+    updateStmt.run(duration, row.id);
+    try {
+      const payload = JSON.stringify({
+        code: "RewindFailed",
+        needsAttention: true,
+        message: `Rewind audit ${row.id} was in_progress at startup; marked partial.`,
+        timestampMs: now,
+      });
+      await adapter.updateRun(row.runId, {
+        status: "needs_attention",
+        heartbeatAtMs: null,
+        runtimeOwnerId: null,
+        errorJson: payload,
+      });
+    } catch {
+      try {
+        await adapter.updateRun(row.runId, {
+          status: "failed",
+          heartbeatAtMs: null,
+          runtimeOwnerId: null,
+          errorJson: JSON.stringify({
+            code: "RewindFailed",
+            needsAttention: true,
+            message: "Rewind was in_progress at startup.",
+            timestampMs: now,
+          }),
+        });
+      } catch {
+        // best-effort: nothing to do if the run row was deleted.
+      }
+    }
+    recovered.push({ id: row.id, runId: row.runId });
+  }
+  return { recovered };
+}

package/src/replay.js

@@ -0,0 +1,22 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./ReplayResult.ts").ReplayResult} ReplayResult */
+// @smithers-type-exports-end
+
+import { Effect } from "effect";
+import * as BunContext from "@effect/platform-bun/BunContext";
+import { replayFromCheckpoint as replayFromCheckpointEffect } from "./replayFromCheckpointEffect.js";
+export { replayFromCheckpointEffect };
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("./ReplayParams.ts").ReplayParams} ReplayParams */
+
+/**
+ * Fork a run from a checkpoint and optionally restore the VCS working copy.
+ *
+ * @param {SmithersDb} adapter
+ * @param {ReplayParams} params
+ * @returns {Promise<ReplayResult>}
+ */
+export function replayFromCheckpoint(adapter, params) {
+    return Effect.runPromise(replayFromCheckpointEffect(adapter, params).pipe(Effect.provide(BunContext.layer)));
+}

package/src/replayFromCheckpointEffect.js

@@ -0,0 +1,59 @@
+import { Effect, Metric } from "effect";
+import { forkRun as forkRunEffect } from "./fork/forkRunEffect.js";
+import { rerunAtRevision as rerunAtRevisionEffect } from "./vcs-version/rerunAtRevisionEffect.js";
+import { replaysStarted } from "./replaysStarted.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("./ReplayParams.ts").ReplayParams} ReplayParams */
+/** @typedef {import("./ReplayResult.ts").ReplayResult} ReplayResult */
+
+/**
+ * Fork a run from a checkpoint, optionally restore the VCS working copy
+ * to the revision that was active at the source frame, then return the
+ * new run metadata so the caller can resume execution.
+ *
+ * @param {SmithersDb} adapter
+ * @param {ReplayParams} params
+ */
+export function replayFromCheckpoint(adapter, params) {
+    return Effect.gen(function* () {
+        const { parentRunId, frameNo, inputOverrides, resetNodes, branchLabel, restoreVcs, cwd, } = params;
+        // 1. Fork the run
+        const { runId, branch, snapshot } = yield* forkRunEffect(adapter, {
+            parentRunId,
+            frameNo,
+            inputOverrides,
+            resetNodes,
+            branchLabel,
+            forkDescription: `Replay from ${parentRunId}:${frameNo}`,
+        });
+        // 2. Optionally restore VCS state
+        let vcsRestored = false;
+        let vcsPointer = null;
+        let vcsError;
+        if (restoreVcs) {
+            const vcsResult = yield* rerunAtRevisionEffect(adapter, parentRunId, frameNo, { cwd });
+            vcsRestored = vcsResult.restored;
+            vcsPointer = vcsResult.vcsPointer;
+            vcsError = vcsResult.error;
+        }
+        yield* Metric.increment(replaysStarted);
+        yield* Effect.logInfo("Replay started").pipe(Effect.annotateLogs({
+            parentRunId,
+            parentFrameNo: String(frameNo),
+            childRunId: runId,
+            vcsRestored: String(vcsRestored),
+        }));
+        return {
+            runId,
+            branch,
+            snapshot,
+            vcsRestored,
+            vcsPointer,
+            vcsError,
+        };
+    }).pipe(Effect.annotateLogs({
+        parentRunId: params.parentRunId,
+        parentFrameNo: String(params.frameNo),
+    }), Effect.withLogSpan("time-travel:replay-from-checkpoint"));
+}

package/src/replaysStarted.js

@@ -0,0 +1,2 @@
+import { Metric } from "effect";
+export const replaysStarted = Metric.counter("smithers.replays.started");

package/src/resetRewindLocksForTests.js

@@ -0,0 +1,8 @@
+import { rewindLockStore } from "./rewindLockStore.js";
+
+/**
+ * Reset lock state for tests.
+ */
+export function resetRewindLocksForTests() {
+  rewindLockStore.clear();
+}

package/src/resolveRewindAuditClient.js

@@ -0,0 +1,38 @@
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * Minimal Bun SQLite client surface used by the rewind audit helpers.
+ * This mirrors the shape returned by `bun:sqlite`'s `Database.query()`
+ * and is sufficient for the raw SQL writes / reads we perform against
+ * the `_smithers_time_travel_audit` and `_smithers_frames` tables.
+ *
+ * @typedef {{
+ *   query: (sql: string) => {
+ *     run: (...args: unknown[]) => unknown;
+ *     get: (...args: unknown[]) => Record<string, unknown> | null | undefined;
+ *     all: (...args: unknown[]) => Array<Record<string, unknown>>;
+ *   };
+ * }} RewindAuditSqliteClient
+ */
+
+/**
+ * Resolve the Bun SQLite client from a {@link SmithersDb} instance for audit writes.
+ *
+ * @param {SmithersDb} adapter
+ * @returns {RewindAuditSqliteClient}
+ */
+export function resolveRewindAuditClient(adapter) {
+  const db = /** @type {{ session?: { client?: unknown }; $client?: unknown } | null | undefined} */ (
+    /** @type {unknown} */ (adapter?.db)
+  );
+  const candidate = /** @type {unknown} */ (db?.session?.client ?? db?.$client);
+  if (
+    !candidate ||
+    typeof (/** @type {{ query?: unknown }} */ (candidate).query) !== "function"
+  ) {
+    throw new TypeError(
+      "Could not resolve a Bun SQLite client for rewind audit writes.",
+    );
+  }
+  return /** @type {RewindAuditSqliteClient} */ (candidate);
+}

package/src/retry-task.js

@@ -0,0 +1,215 @@
+import { Effect } from "effect";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+/** @typedef {import("./RetryTaskOptions.ts").RetryTaskOptions} RetryTaskOptions */
+/** @typedef {import("./RetryTaskResult.ts").RetryTaskResult} RetryTaskResult */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * @param {string} nodeId
+ * @param {number} iteration
+ */
+function buildNodeKey(nodeId, iteration) {
+    return `${nodeId}::${iteration}`;
+}
+/**
+ * @param {Array<{ nodeId: string; iteration: number }>} nodes
+ * @returns {string[]}
+ */
+function uniqueNodeIds(nodes) {
+    const seen = new Set();
+    const result = [];
+    for (const node of nodes) {
+        if (seen.has(node.nodeId))
+            continue;
+        seen.add(node.nodeId);
+        result.push(node.nodeId);
+    }
+    return result;
+}
+/**
+ * @param {string | null | undefined} status
+ */
+function isActiveRunStatus(status) {
+    return (status === "running" ||
+        status === "waiting-approval" ||
+        status === "waiting-event" ||
+        status === "waiting-timer");
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {Required<Pick<RetryTaskOptions, "runId" | "resetDependents">> & { targetNode: any; }} opts
+ */
+async function resolveResetNodes(adapter, opts) {
+    const { runId, targetNode, resetDependents } = opts;
+    if (!resetDependents) {
+        return [targetNode];
+    }
+    const nodes = await adapter.listNodes(runId);
+    const attempts = await adapter.listAttemptsForRun(runId);
+    const attemptOrder = new Map();
+    for (let index = 0; index < attempts.length; index += 1) {
+        const attempt = attempts[index];
+        attemptOrder.set(buildNodeKey(attempt.nodeId, attempt.iteration ?? 0), index);
+    }
+    const targetKey = buildNodeKey(targetNode.nodeId, targetNode.iteration ?? 0);
+    const targetOrder = attemptOrder.get(targetKey);
+    const targetIteration = targetNode.iteration ?? 0;
+    const targetUpdatedAtMs = targetNode.updatedAtMs ?? 0;
+    return nodes.filter((node) => {
+        const nodeIteration = node.iteration ?? 0;
+        const nodeKey = buildNodeKey(node.nodeId, nodeIteration);
+        if (nodeKey === targetKey)
+            return true;
+        if (nodeIteration > targetIteration)
+            return true;
+        const nodeOrder = attemptOrder.get(nodeKey);
+        if (targetOrder !== undefined && nodeOrder !== undefined) {
+            return nodeOrder > targetOrder;
+        }
+        return (node.updatedAtMs ?? 0) > targetUpdatedAtMs;
+    });
+}
+/**
+ * @param {RetryTaskOptions} opts
+ * @param {{ runId: string; nodeId: string; iteration: number; resetNodes: string[]; success: boolean; error?: string; }} payload
+ */
+function emitRetryFinished(opts, payload) {
+    opts.onProgress?.({
+        type: "RetryTaskFinished",
+        ...payload,
+        timestampMs: nowMs(),
+    });
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {RetryTaskOptions} opts
+ * @returns {Promise<RetryTaskResult>}
+ */
+export async function retryTask(adapter, opts) {
+    const runId = opts.runId;
+    const nodeId = opts.nodeId;
+    const iteration = opts.iteration ?? 0;
+    const resetDependents = opts.resetDependents ?? true;
+    const force = opts.force ?? false;
+    const node = await adapter.getNode(runId, nodeId, iteration);
+    if (!node) {
+        const error = `Node not found: ${runId}/${nodeId}/${iteration}`;
+        emitRetryFinished(opts, {
+            runId,
+            nodeId,
+            iteration,
+            resetNodes: [],
+            success: false,
+            error,
+        });
+        return { success: false, resetNodes: [], error };
+    }
+    const run = await adapter.getRun(runId);
+    if (!run) {
+        const error = `Run not found: ${runId}`;
+        emitRetryFinished(opts, {
+            runId,
+            nodeId,
+            iteration,
+            resetNodes: [],
+            success: false,
+            error,
+        });
+        return { success: false, resetNodes: [], error };
+    }
+    if (!force && isActiveRunStatus(run.status)) {
+        const error = `Run is still running: ${runId}`;
+        emitRetryFinished(opts, {
+            runId,
+            nodeId,
+            iteration,
+            resetNodes: [],
+            success: false,
+            error,
+        });
+        return { success: false, resetNodes: [], error };
+    }
+    const resetNodes = await resolveResetNodes(adapter, {
+        runId,
+        targetNode: node,
+        resetDependents,
+    });
+    const resetNodeIds = uniqueNodeIds(resetNodes.map((candidate) => ({
+        nodeId: candidate.nodeId,
+        iteration: candidate.iteration ?? 0,
+    })));
+    const attemptsByNode = new Map();
+    for (const resetNode of resetNodes) {
+        const resetIteration = resetNode.iteration ?? 0;
+        attemptsByNode.set(buildNodeKey(resetNode.nodeId, resetIteration), await adapter.listAttempts(runId, resetNode.nodeId, resetIteration));
+    }
+    opts.onProgress?.({
+        type: "RetryTaskStarted",
+        runId,
+        nodeId,
+        iteration,
+        resetDependents,
+        resetNodes: resetNodeIds,
+        timestampMs: nowMs(),
+    });
+    const resetTimestampMs = nowMs();
+    await adapter.withTransaction("retry-task-reset", Effect.gen(function* () {
+        for (const resetNode of resetNodes) {
+            const resetIteration = resetNode.iteration ?? 0;
+            const attempts = attemptsByNode.get(buildNodeKey(resetNode.nodeId, resetIteration)) ??
+                [];
+            for (const attempt of attempts) {
+                if (attempt.state !== "failed" &&
+                    attempt.state !== "in-progress" &&
+                    attempt.state !== "waiting-approval" &&
+                    attempt.state !== "waiting-event" &&
+                    attempt.state !== "waiting-timer") {
+                    continue;
+                }
+                const patch = { state: "cancelled" };
+                if (attempt.finishedAtMs == null) {
+                    patch.finishedAtMs = resetTimestampMs;
+                }
+                yield* adapter.updateAttemptEffect(runId, resetNode.nodeId, resetIteration, attempt.attempt, patch);
+            }
+            if (resetNode.outputTable) {
+                yield* adapter.deleteOutputRowEffect(resetNode.outputTable, {
+                    runId,
+                    nodeId: resetNode.nodeId,
+                    iteration: resetIteration,
+                });
+            }
+            yield* adapter.insertNodeEffect({
+                runId,
+                nodeId: resetNode.nodeId,
+                iteration: resetIteration,
+                state: "pending",
+                lastAttempt: resetNode.lastAttempt ?? null,
+                updatedAtMs: resetTimestampMs,
+                outputTable: resetNode.outputTable ?? "",
+                label: resetNode.label ?? null,
+            });
+        }
+        yield* adapter.updateRunEffect(runId, {
+            status: "running",
+            finishedAtMs: null,
+            heartbeatAtMs: null,
+            runtimeOwnerId: null,
+            cancelRequestedAtMs: null,
+            hijackRequestedAtMs: null,
+            hijackTarget: null,
+            errorJson: null,
+        });
+    }));
+    emitRetryFinished(opts, {
+        runId,
+        nodeId,
+        iteration,
+        resetNodes: resetNodeIds,
+        success: true,
+    });
+    return {
+        success: true,
+        resetNodes: resetNodeIds,
+    };
+}

package/src/revert.js

@@ -0,0 +1,68 @@
+import { Effect } from "effect";
+import { revertToJjPointer } from "@smithers-orchestrator/vcs/jj";
+import * as BunContext from "@effect/platform-bun/BunContext";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+/** @typedef {import("./RevertOptions.ts").RevertOptions} RevertOptions */
+/** @typedef {import("./RevertResult.ts").RevertResult} RevertResult */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {RevertOptions} opts
+ * @returns {Promise<RevertResult>}
+ */
+export async function revertToAttempt(adapter, opts) {
+    const { runId, nodeId, iteration, attempt, onProgress } = opts;
+    const attemptRow = await Effect.runPromise(adapter.getAttempt(runId, nodeId, iteration, attempt));
+    if (!attemptRow) {
+        return {
+            success: false,
+            error: `Attempt not found: ${runId}/${nodeId}/${iteration}/${attempt}`,
+        };
+    }
+    const jjPointer = attemptRow.jjPointer;
+    if (!jjPointer) {
+        return { success: false, error: `Attempt has no jjPointer recorded` };
+    }
+    onProgress?.({
+        type: "RevertStarted",
+        runId,
+        nodeId,
+        iteration,
+        attempt,
+        jjPointer,
+        timestampMs: nowMs(),
+    });
+    // Revert must target the same repository/worktree where the attempt ran.
+    const cwd = attemptRow.jjCwd ?? undefined;
+    const result = await Effect.runPromise(revertToJjPointer(jjPointer, cwd).pipe(Effect.provide(BunContext.layer)));
+    onProgress?.({
+        type: "RevertFinished",
+        runId,
+        nodeId,
+        iteration,
+        attempt,
+        jjPointer,
+        success: result.success,
+        error: result.error,
+        timestampMs: nowMs(),
+    });
+    if (!result.success) {
+        return { success: false, error: result.error, jjPointer };
+    }
+    // Clean up DB frames recorded after the reverted attempt started.
+    // Find the latest frame created before the attempt's start time and
+    // discard everything after it so the DB matches the reverted VCS state.
+    const frames = await Effect.runPromise(adapter.listFrames(runId, 1_000_000));
+    const cutoff = attemptRow.startedAtMs;
+    let lastValidFrameNo = -1;
+    for (const f of frames) {
+        if (f.createdAtMs <= cutoff && f.frameNo > lastValidFrameNo) {
+            lastValidFrameNo = f.frameNo;
+        }
+    }
+    if (lastValidFrameNo >= 0) {
+        await Effect.runPromise(adapter.deleteFramesAfter(runId, lastValidFrameNo));
+    }
+    return { success: true, jjPointer };
+}

package/src/rewindAudit.js

@@ -0,0 +1,9 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./RewindAuditResult.ts").RewindAuditResult} RewindAuditResult */
+// @smithers-type-exports-end
+
+export { writeRewindAuditRow } from "./writeRewindAuditRow.js";
+export { updateRewindAuditRow } from "./updateRewindAuditRow.js";
+export { countRecentRewindAuditRows } from "./countRecentRewindAuditRows.js";
+export { listRewindAuditRows } from "./listRewindAuditRows.js";
+export { recoverInProgressRewindAudits } from "./recoverInProgressRewindAudits.js";

package/src/rewindLock.js

@@ -0,0 +1,7 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./RewindLockHandle.ts").RewindLockHandle} RewindLockHandle */
+// @smithers-type-exports-end
+
+export { acquireRewindLock } from "./acquireRewindLock.js";
+export { hasRewindLock } from "./hasRewindLock.js";
+export { resetRewindLocksForTests } from "./resetRewindLocksForTests.js";

package/src/rewindLockStore.js

@@ -0,0 +1,8 @@
+/**
+ * Shared per-run single-flight lock table.
+ * Used by {@link acquireRewindLock}, {@link hasRewindLock},
+ * and {@link resetRewindLocksForTests}.
+ *
+ * @type {Map<string, symbol>}
+ */
+export const rewindLockStore = new Map();

package/src/rewindRateLimit.js

@@ -0,0 +1,3 @@
+export { REWIND_RATE_LIMIT_MAX } from "./REWIND_RATE_LIMIT_MAX.js";
+export { REWIND_RATE_LIMIT_WINDOW_MS } from "./REWIND_RATE_LIMIT_WINDOW_MS.js";
+export { evaluateRewindRateLimit } from "./evaluateRewindRateLimit.js";

package/src/runForksCreated.js

@@ -0,0 +1,2 @@
+import { Metric } from "effect";
+export const runForksCreated = Metric.counter("smithers.forks.created");

package/src/schema.js

@@ -0,0 +1,46 @@
+import { integer, sqliteTable, text, primaryKey, } from "drizzle-orm/sqlite-core";
+/**
+ * Full state snapshot captured at each frame commit.
+ * PK: (run_id, frame_no)
+ */
+export const smithersSnapshots = sqliteTable("_smithers_snapshots", {
+    runId: text("run_id").notNull(),
+    frameNo: integer("frame_no").notNull(),
+    nodesJson: text("nodes_json").notNull(),
+    outputsJson: text("outputs_json").notNull(),
+    ralphJson: text("ralph_json").notNull(),
+    inputJson: text("input_json").notNull(),
+    vcsPointer: text("vcs_pointer"),
+    workflowHash: text("workflow_hash"),
+    contentHash: text("content_hash").notNull(),
+    createdAtMs: integer("created_at_ms").notNull(),
+}, (t) => ({
+    pk: primaryKey({ columns: [t.runId, t.frameNo] }),
+}));
+/**
+ * Parent-child fork relationships between runs.
+ * PK: run_id (the child run)
+ */
+export const smithersBranches = sqliteTable("_smithers_branches", {
+    runId: text("run_id").primaryKey(),
+    parentRunId: text("parent_run_id").notNull(),
+    parentFrameNo: integer("parent_frame_no").notNull(),
+    branchLabel: text("branch_label"),
+    forkDescription: text("fork_description"),
+    createdAtMs: integer("created_at_ms").notNull(),
+});
+/**
+ * VCS revision metadata per snapshot.
+ * PK: (run_id, frame_no)
+ */
+export const smithersVcsTags = sqliteTable("_smithers_vcs_tags", {
+    runId: text("run_id").notNull(),
+    frameNo: integer("frame_no").notNull(),
+    vcsType: text("vcs_type").notNull(),
+    vcsPointer: text("vcs_pointer").notNull(),
+    vcsRoot: text("vcs_root"),
+    jjOperationId: text("jj_operation_id"),
+    createdAtMs: integer("created_at_ms").notNull(),
+}, (t) => ({
+    pk: primaryKey({ columns: [t.runId, t.frameNo] }),
+}));

package/src/snapshot/Snapshot.ts

@@ -0,0 +1,15 @@
+/**
+ * Serialized snapshot of workflow state at a specific frame.
+ */
+export type Snapshot = {
+  runId: string;
+  frameNo: number;
+  nodesJson: string;
+  outputsJson: string;
+  ralphJson: string;
+  inputJson: string;
+  vcsPointer: string | null;
+  workflowHash: string | null;
+  contentHash: string;
+  createdAtMs: number;
+};