@smithers-orchestrator/time-travel 0.16.0

package/src/timetravel.js

@@ -0,0 +1,247 @@
+import { Effect } from "effect";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+import { revertToJjPointer } from "@smithers-orchestrator/vcs/jj";
+import * as BunContext from "@effect/platform-bun/BunContext";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("./TimeTravelOptions.ts").TimeTravelOptions} TimeTravelOptions */
+/** @typedef {import("./TimeTravelResult.ts").TimeTravelResult} TimeTravelResult */
+
+/**
+ * @param {string} nodeId
+ * @param {number} iteration
+ */
+function nodeKey(nodeId, iteration) {
+    return `${nodeId}::${iteration}`;
+}
+/**
+ * @param {Array<{ nodeId: string; iteration: number }>} nodes
+ */
+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 {any[]} attempts
+ * @param {number} [requestedAttempt]
+ * @returns {AttemptRow | undefined}
+ */
+function selectAttempt(attempts, requestedAttempt) {
+    if (requestedAttempt == null)
+        return attempts[0];
+    return attempts.find((attempt) => attempt.attempt === requestedAttempt);
+}
+/**
+ * @param {NonNullable<AttemptRow>} targetAttempt
+ * @param {any[]} attemptsForRun
+ */
+function findTargetAttemptOrder(targetAttempt, attemptsForRun) {
+    return attemptsForRun.findIndex((attempt) => attempt.runId === targetAttempt.runId &&
+        attempt.nodeId === targetAttempt.nodeId &&
+        (attempt.iteration ?? 0) === (targetAttempt.iteration ?? 0) &&
+        attempt.attempt === targetAttempt.attempt);
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {{ runId: string; targetNode: NonNullable<NodeRow>; targetAttempt: NonNullable<AttemptRow>; attemptsForRun: any[]; resetDependents: boolean; }} opts
+ */
+async function resolveResetNodes(adapter, opts) {
+    const { runId, targetNode, targetAttempt, attemptsForRun, resetDependents } = opts;
+    if (!resetDependents) {
+        return [targetNode];
+    }
+    const nodes = await Effect.runPromise(adapter.listNodes(runId));
+    const targetKey = nodeKey(targetNode.nodeId, targetNode.iteration ?? 0);
+    const targetAttemptOrder = findTargetAttemptOrder(targetAttempt, attemptsForRun);
+    const targetIteration = targetNode.iteration ?? 0;
+    const cutoff = targetAttempt.startedAtMs;
+    return nodes.filter((node) => {
+        const currentKey = nodeKey(node.nodeId, node.iteration ?? 0);
+        if (currentKey === targetKey)
+            return true;
+        if ((node.iteration ?? 0) > targetIteration)
+            return true;
+        let startedAfterTarget = false;
+        let orderedAfterTarget = false;
+        for (let index = 0; index < attemptsForRun.length; index += 1) {
+            const attempt = attemptsForRun[index];
+            if (attempt.nodeId !== node.nodeId ||
+                (attempt.iteration ?? 0) !== (node.iteration ?? 0)) {
+                continue;
+            }
+            if ((attempt.startedAtMs ?? 0) >= cutoff) {
+                startedAfterTarget = true;
+            }
+            if (targetAttemptOrder >= 0 && index > targetAttemptOrder) {
+                orderedAfterTarget = true;
+            }
+        }
+        return startedAfterTarget || orderedAfterTarget;
+    });
+}
+/**
+ * @param {NonNullable<NodeRow>} existingNode
+ */
+function buildPendingNode(existingNode) {
+    return {
+        ...existingNode,
+        state: "pending",
+        updatedAtMs: nowMs(),
+    };
+}
+/**
+ * @param {SmithersDb} adapter
+ * @param {TimeTravelOptions} opts
+ * @returns {Promise<TimeTravelResult>}
+ */
+export async function timeTravel(adapter, opts) {
+    const runId = opts.runId;
+    const nodeId = opts.nodeId;
+    const iteration = opts.iteration ?? 0;
+    const resetDependents = opts.resetDependents ?? true;
+    const restoreVcs = opts.restoreVcs ?? true;
+    const attempts = await Effect.runPromise(adapter.listAttempts(runId, nodeId, iteration));
+    const targetAttempt = selectAttempt(attempts, opts.attempt);
+    if (!targetAttempt) {
+        return {
+            success: false,
+            vcsRestored: false,
+            resetNodes: [],
+            error: `Attempt not found: ${runId}/${nodeId}/${iteration}/${opts.attempt ?? "latest"}`,
+        };
+    }
+    const targetAttemptNo = targetAttempt.attempt;
+    const jjPointer = targetAttempt.jjPointer ?? undefined;
+    const targetNode = await Effect.runPromise(adapter.getNode(runId, nodeId, iteration));
+    if (!targetNode) {
+        return {
+            success: false,
+            vcsRestored: false,
+            resetNodes: [],
+            error: `Node not found: ${runId}/${nodeId}/${iteration}`,
+        };
+    }
+    opts.onProgress?.({
+        type: "TimeTravelStarted",
+        runId,
+        nodeId,
+        iteration,
+        attempt: targetAttemptNo,
+        jjPointer,
+        timestampMs: nowMs(),
+    });
+    let vcsRestored = false;
+    if (restoreVcs && jjPointer) {
+        const vcsResult = await Effect.runPromise(revertToJjPointer(jjPointer, targetAttempt.jjCwd ?? undefined).pipe(Effect.provide(BunContext.layer)));
+        vcsRestored = vcsResult.success;
+        if (!vcsResult.success) {
+            const error = vcsResult.error ?? "Failed to restore VCS state";
+            opts.onProgress?.({
+                type: "TimeTravelFinished",
+                runId,
+                nodeId,
+                iteration,
+                attempt: targetAttemptNo,
+                jjPointer,
+                success: false,
+                vcsRestored,
+                resetNodes: [],
+                error,
+                timestampMs: nowMs(),
+            });
+            return {
+                success: false,
+                jjPointer,
+                vcsRestored,
+                resetNodes: [],
+                error,
+            };
+        }
+    }
+    const attemptsForRun = await Effect.runPromise(adapter.listAttemptsForRun(runId));
+    const resetNodes = await resolveResetNodes(adapter, {
+        runId,
+        targetNode,
+        targetAttempt,
+        attemptsForRun,
+        resetDependents,
+    });
+    const resetNodeIds = uniqueNodeIds(resetNodes.map((node) => ({
+        nodeId: node.nodeId,
+        iteration: node.iteration ?? 0,
+    })));
+    const attemptsByNode = new Map();
+    for (const resetNode of resetNodes) {
+        attemptsByNode.set(nodeKey(resetNode.nodeId, resetNode.iteration ?? 0), attemptsForRun.filter((attempt) => attempt.nodeId === resetNode.nodeId &&
+            (attempt.iteration ?? 0) === (resetNode.iteration ?? 0)));
+    }
+    await adapter.withTransaction("time-travel", Effect.gen(function* () {
+        const frames = yield* adapter.listFrames(runId, 1_000_000);
+        const cutoff = targetAttempt.startedAtMs;
+        let lastValidFrameNo = -1;
+        for (const frame of frames) {
+            if (frame.createdAtMs <= cutoff && frame.frameNo > lastValidFrameNo) {
+                lastValidFrameNo = frame.frameNo;
+            }
+        }
+        if (lastValidFrameNo >= 0) {
+            yield* adapter.deleteFramesAfter(runId, lastValidFrameNo);
+        }
+        for (const resetNode of resetNodes) {
+            const attemptsForNode = attemptsByNode.get(nodeKey(resetNode.nodeId, resetNode.iteration ?? 0)) ??
+                [];
+            for (const attempt of attemptsForNode) {
+                if ((attempt.startedAtMs ?? 0) < cutoff || attempt.state === "cancelled") {
+                    continue;
+                }
+                const patch = { state: "cancelled" };
+                if (attempt.finishedAtMs == null) {
+                    patch.finishedAtMs = nowMs();
+                }
+                yield* adapter.updateAttempt(runId, resetNode.nodeId, resetNode.iteration ?? 0, attempt.attempt, patch);
+            }
+            if (resetNode.outputTable) {
+                yield* adapter.deleteOutputRow(resetNode.outputTable, {
+                    runId,
+                    nodeId: resetNode.nodeId,
+                    iteration: resetNode.iteration ?? 0,
+                });
+            }
+            yield* adapter.insertNode(buildPendingNode(resetNode));
+        }
+        yield* adapter.updateRun(runId, {
+            status: "running",
+            finishedAtMs: null,
+            heartbeatAtMs: null,
+            runtimeOwnerId: null,
+            cancelRequestedAtMs: null,
+            hijackRequestedAtMs: null,
+            hijackTarget: null,
+            errorJson: null,
+        });
+    }));
+    opts.onProgress?.({
+        type: "TimeTravelFinished",
+        runId,
+        nodeId,
+        iteration,
+        attempt: targetAttemptNo,
+        jjPointer,
+        success: true,
+        vcsRestored,
+        resetNodes: resetNodeIds,
+        timestampMs: nowMs(),
+    });
+    return {
+        success: true,
+        jjPointer,
+        vcsRestored,
+        resetNodes: resetNodeIds,
+    };
+}

package/src/types.ts

@@ -0,0 +1,15 @@
+// Barrel re-export for backward compatibility with @smithers-orchestrator/time-travel/types imports
+export type { Snapshot } from "./snapshot/Snapshot";
+export type { ParsedSnapshot } from "./ParsedSnapshot";
+export type { NodeSnapshot } from "./NodeSnapshot";
+export type { RalphSnapshot } from "./RalphSnapshot";
+export type { SnapshotDiff } from "./SnapshotDiff";
+export type { NodeChange } from "./NodeChange";
+export type { OutputChange } from "./OutputChange";
+export type { RalphChange } from "./RalphChange";
+export type { ForkParams } from "./ForkParams";
+export type { ReplayParams } from "./ReplayParams";
+export type { BranchInfo } from "./BranchInfo";
+export type { TimelineFrame } from "./TimelineFrame";
+export type { RunTimeline } from "./RunTimeline";
+export type { TimelineTree } from "./TimelineTree";

package/src/updateRewindAuditRow.js

@@ -0,0 +1,35 @@
+import { resolveRewindAuditClient } from "./resolveRewindAuditClient.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("./RewindAuditResult.ts").RewindAuditResult} RewindAuditResult */
+
+/**
+ * Update an existing rewind audit row's result and duration.
+ * Used to mark an `in_progress` row as `success`, `failed`, or `partial`.
+ *
+ * @param {SmithersDb} adapter
+ * @param {{ id: number; result: RewindAuditResult; durationMs?: number | null; fromFrameNo?: number }} row
+ */
+export async function updateRewindAuditRow(adapter, row) {
+  const client = resolveRewindAuditClient(adapter);
+  if (typeof row.fromFrameNo === "number") {
+    client
+      .query(
+        `UPDATE _smithers_time_travel_audit
+            SET result = ?,
+                duration_ms = ?,
+                from_frame_no = ?
+          WHERE id = ?`,
+      )
+      .run(row.result, row.durationMs ?? null, row.fromFrameNo, row.id);
+    return;
+  }
+  client
+    .query(
+      `UPDATE _smithers_time_travel_audit
+          SET result = ?,
+              duration_ms = ?
+        WHERE id = ?`,
+    )
+    .run(row.result, row.durationMs ?? null, row.id);
+}

package/src/validateJumpFrameNo.js

@@ -0,0 +1,23 @@
+import { JUMP_MAX_FRAME_NO } from "./JUMP_MAX_FRAME_NO.js";
+import { JumpToFrameError } from "./JumpToFrameError.js";
+
+/**
+ * Validate a jump frame number argument.
+ *
+ * @param {unknown} frameNo
+ * @returns {number}
+ */
+export function validateJumpFrameNo(frameNo) {
+  if (
+    typeof frameNo !== "number" ||
+    !Number.isInteger(frameNo) ||
+    frameNo < 0 ||
+    frameNo > JUMP_MAX_FRAME_NO
+  ) {
+    throw new JumpToFrameError(
+      "InvalidFrameNo",
+      "frameNo must be a non-negative i32 integer.",
+    );
+  }
+  return frameNo;
+}

package/src/validateJumpRunId.js

@@ -0,0 +1,18 @@
+import { JUMP_RUN_ID_PATTERN } from "./JUMP_RUN_ID_PATTERN.js";
+import { JumpToFrameError } from "./JumpToFrameError.js";
+
+/**
+ * Validate a jump run id argument.
+ *
+ * @param {unknown} runId
+ * @returns {string}
+ */
+export function validateJumpRunId(runId) {
+  if (typeof runId !== "string" || !JUMP_RUN_ID_PATTERN.test(runId)) {
+    throw new JumpToFrameError(
+      "InvalidRunId",
+      "runId must match /^[a-z0-9_-]{1,64}$/.",
+    );
+  }
+  return runId;
+}

package/src/vcs-version/VcsTag.ts

@@ -0,0 +1,9 @@
+export type VcsTag = {
+  runId: string;
+  frameNo: number;
+  vcsType: string;
+  vcsPointer: string;
+  vcsRoot: string | null;
+  jjOperationId: string | null;
+  createdAtMs: number;
+};

package/src/vcs-version/index.js

@@ -0,0 +1,61 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./VcsTag.ts").VcsTag} VcsTag */
+// @smithers-type-exports-end
+
+import { Effect } from "effect";
+import * as BunContext from "@effect/platform-bun/BunContext";
+import { loadVcsTag as loadVcsTagEffect } from "./loadVcsTagEffect.js";
+import { rerunAtRevision as rerunAtRevisionEffect } from "./rerunAtRevisionEffect.js";
+import { resolveWorkflowAtRevision as resolveWorkflowAtRevisionEffect } from "./resolveWorkflowAtRevisionEffect.js";
+import { tagSnapshotVcs as tagSnapshotVcsEffect } from "./tagSnapshotVcsEffect.js";
+export { loadVcsTagEffect, rerunAtRevisionEffect, resolveWorkflowAtRevisionEffect, tagSnapshotVcsEffect, };
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * Record the current VCS revision for a run/frame pair.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {{ cwd?: string }} [opts]
+ * @returns {Promise<VcsTag | null>}
+ */
+export function tagSnapshotVcs(adapter, runId, frameNo, opts = {}) {
+    return Effect.runPromise(tagSnapshotVcsEffect(adapter, runId, frameNo, opts).pipe(Effect.provide(BunContext.layer)));
+}
+/**
+ * Load the VCS revision tag for a run/frame pair, if any.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @returns {Promise<VcsTag | undefined>}
+ */
+export function loadVcsTag(adapter, runId, frameNo) {
+    return Effect.runPromise(loadVcsTagEffect(adapter, runId, frameNo));
+}
+/**
+ * Create a jj workspace at the revision recorded for a run/frame pair.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {string} workspacePath
+ * @returns {Promise<{ workspacePath: string; vcsPointer: string } | null>}
+ */
+export function resolveWorkflowAtRevision(adapter, runId, frameNo, workspacePath) {
+    return Effect.runPromise(resolveWorkflowAtRevisionEffect(adapter, runId, frameNo, workspacePath).pipe(Effect.provide(BunContext.layer)));
+}
+/**
+ * Revert the working copy to the VCS revision for a run/frame pair.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {{ cwd?: string }} [opts]
+ * @returns {Promise<{ restored: boolean; vcsPointer: string | null; error?: string }>}
+ */
+export function rerunAtRevision(adapter, runId, frameNo, opts = {}) {
+    return Effect.runPromise(rerunAtRevisionEffect(adapter, runId, frameNo, opts).pipe(Effect.provide(BunContext.layer)));
+}

package/src/vcs-version/loadVcsTagEffect.js

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

package/src/vcs-version/rerunAtRevisionEffect.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { revertToJjPointer } from "@smithers-orchestrator/vcs/jj";
+import { loadVcsTag } from "./loadVcsTagEffect.js";
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {{ cwd?: string }} [opts]
+ * @returns {Effect.Effect< { restored: boolean; vcsPointer: string | null; error?: string }, SmithersError, CommandExecutor >}
+ */
+export function rerunAtRevision(adapter, runId, frameNo, opts = {}) {
+    return Effect.gen(function* () {
+        const tag = yield* loadVcsTag(adapter, runId, frameNo);
+        if (!tag) {
+            return { restored: false, vcsPointer: null };
+        }
+        const result = yield* revertToJjPointer(tag.vcsPointer, opts.cwd ?? tag.vcsRoot ?? undefined);
+        if (!result.success) {
+            return { restored: false, vcsPointer: tag.vcsPointer, error: result.error };
+        }
+        return { restored: true, vcsPointer: tag.vcsPointer };
+    }).pipe(Effect.annotateLogs({ runId, frameNo: String(frameNo) }), Effect.withLogSpan("time-travel:rerun-at-revision"));
+}

package/src/vcs-version/resolveWorkflowAtRevisionEffect.js

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { workspaceAdd } from "@smithers-orchestrator/vcs/jj";
+import { loadVcsTag } from "./loadVcsTagEffect.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * Create a jj workspace at the revision recorded for a specific snapshot.
+ * Returns the workspace path or null if no VCS tag exists.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {string} workspacePath
+ */
+export function resolveWorkflowAtRevision(adapter, runId, frameNo, workspacePath) {
+    return Effect.gen(function* () {
+        const tag = yield* loadVcsTag(adapter, runId, frameNo);
+        if (!tag)
+            return null;
+        const workspaceName = `smithers-replay-${runId.slice(0, 8)}-f${frameNo}`;
+        const result = yield* workspaceAdd(workspaceName, workspacePath, {
+            cwd: tag.vcsRoot ?? undefined,
+            atRev: tag.vcsPointer,
+        });
+        if (!result.success) {
+            return yield* Effect.fail(new SmithersError("VCS_WORKSPACE_CREATE_FAILED", `Failed to create workspace at ${tag.vcsPointer}: ${result.error}`, { frameNo, runId, vcsPointer: tag.vcsPointer, workspacePath }));
+        }
+        return { workspacePath, vcsPointer: tag.vcsPointer };
+    }).pipe(Effect.annotateLogs({ runId, frameNo: String(frameNo) }), Effect.withLogSpan("time-travel:resolve-workflow-at-revision"));
+}

package/src/vcs-version/tagSnapshotVcsEffect.js

@@ -0,0 +1,56 @@
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+import { smithersVcsTags } from "../schema.js";
+import { getJjPointer, runJj, } from "@smithers-orchestrator/vcs/jj";
+/** @typedef {import("@effect/platform/CommandExecutor").CommandExecutor} CommandExecutor */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("./VcsTag.ts").VcsTag} VcsTag */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {number} frameNo
+ * @param {{ cwd?: string }} [opts]
+ * @returns {Effect.Effect<VcsTag | null, SmithersError, CommandExecutor>}
+ */
+export function tagSnapshotVcs(adapter, runId, frameNo, opts = {}) {
+    return Effect.gen(function* () {
+        const pointer = yield* getJjPointer(opts.cwd);
+        if (!pointer)
+            return null;
+        // Get current jj operation ID for precise restore
+        const opRes = yield* runJj(["operation", "log", "--no-graph", "--limit", "1", "-T", "self.id()"], { cwd: opts.cwd });
+        const jjOperationId = opRes.code === 0 ? opRes.stdout.trim() || null : null;
+        const ts = nowMs();
+        const tag = {
+            runId,
+            frameNo,
+            vcsType: "jj",
+            vcsPointer: pointer,
+            vcsRoot: opts.cwd ?? null,
+            jjOperationId,
+            createdAtMs: ts,
+        };
+        yield* Effect.tryPromise({
+            try: () => adapter.db
+                .insert(smithersVcsTags)
+                .values(tag)
+                .onConflictDoUpdate({
+                target: [smithersVcsTags.runId, smithersVcsTags.frameNo],
+                set: tag,
+            }),
+            catch: (cause) => toSmithersError(cause, "insert vcs tag", {
+                code: "DB_WRITE_FAILED",
+                details: { frameNo, runId },
+            }),
+        });
+        yield* Effect.logDebug("VCS tag recorded").pipe(Effect.annotateLogs({
+            runId,
+            frameNo: String(frameNo),
+            vcsPointer: pointer,
+        }));
+        return tag;
+    }).pipe(Effect.annotateLogs({ runId, frameNo: String(frameNo) }), Effect.withLogSpan("time-travel:tag-snapshot-vcs"));
+}

package/src/writeRewindAuditRow.js

@@ -0,0 +1,46 @@
+import { resolveRewindAuditClient } from "./resolveRewindAuditClient.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("./RewindAuditResult.ts").RewindAuditResult} RewindAuditResult */
+
+/**
+ * Persist one audit row for a jump-to-frame attempt.
+ *
+ * @param {SmithersDb} adapter
+ * @param {{
+ *   runId: string;
+ *   fromFrameNo: number;
+ *   toFrameNo: number;
+ *   caller: string;
+ *   timestampMs: number;
+ *   result: RewindAuditResult;
+ *   durationMs?: number | null;
+ * }} row
+ * @returns {Promise<number | null>}
+ */
+export async function writeRewindAuditRow(adapter, row) {
+  const client = resolveRewindAuditClient(adapter);
+  client
+    .query(
+      `INSERT INTO _smithers_time_travel_audit (
+         run_id,
+         from_frame_no,
+         to_frame_no,
+         caller,
+         timestamp_ms,
+         result,
+         duration_ms
+       ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      row.runId,
+      row.fromFrameNo,
+      row.toFrameNo,
+      row.caller,
+      row.timestampMs,
+      row.result,
+      row.durationMs ?? null,
+    );
+  const inserted = client.query("SELECT last_insert_rowid() AS id").get();
+  return typeof inserted?.id === "number" ? inserted.id : null;
+}