@smithers-orchestrator/time-travel 0.16.0

package/src/evaluateRewindRateLimit.js

@@ -0,0 +1,41 @@
+import { countRecentRewindAuditRows } from "./countRecentRewindAuditRows.js";
+import { REWIND_RATE_LIMIT_MAX } from "./REWIND_RATE_LIMIT_MAX.js";
+import { REWIND_RATE_LIMIT_WINDOW_MS } from "./REWIND_RATE_LIMIT_WINDOW_MS.js";
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+
+/**
+ * Evaluate caller-scoped rewind quota for one run.
+ *
+ * @param {{
+ *   adapter: SmithersDb;
+ *   runId: string;
+ *   caller: string;
+ *   nowMs?: () => number;
+ *   maxPerWindow?: number;
+ *   windowMs?: number;
+ * }} input
+ */
+export async function evaluateRewindRateLimit(input) {
+  const nowMs = input.nowMs ?? (() => Date.now());
+  const max = Number.isInteger(input.maxPerWindow)
+    ? Math.max(1, Number(input.maxPerWindow))
+    : REWIND_RATE_LIMIT_MAX;
+  const windowMs = Number.isInteger(input.windowMs)
+    ? Math.max(1, Number(input.windowMs))
+    : REWIND_RATE_LIMIT_WINDOW_MS;
+  const windowStartedAtMs = nowMs() - windowMs;
+  const used = await countRecentRewindAuditRows(input.adapter, {
+    runId: input.runId,
+    caller: input.caller,
+    sinceMs: windowStartedAtMs,
+  });
+  return {
+    limited: used >= max,
+    used,
+    remaining: Math.max(0, max - used),
+    max,
+    windowMs,
+    windowStartedAtMs,
+  };
+}

package/src/fork/_helpers.js

@@ -0,0 +1,28 @@
+/**
+ * Given a set of node IDs to reset, compute the full transitive set including
+ * all downstream dependents.  In the absence of an explicit dependency graph,
+ * we reset every node whose iteration >= the minimum iteration of the reset
+ * set. This is intentionally conservative — it re-runs more rather than less.
+ */
+export function expandResetSet(nodes, resetNodeIds) {
+    if (resetNodeIds.length === 0)
+        return [];
+    const resetSet = new Set(resetNodeIds);
+    const result = new Set();
+    // Collect all unique base nodeIds from the snapshot keyed as "nodeId::iteration"
+    for (const key of Object.keys(nodes)) {
+        const baseId = key.split("::")[0];
+        if (resetSet.has(baseId)) {
+            result.add(key);
+        }
+    }
+    // If we found nothing via base nodeId, try exact key match
+    if (result.size === 0) {
+        for (const id of resetNodeIds) {
+            if (nodes[id]) {
+                result.add(id);
+            }
+        }
+    }
+    return [...result];
+}

package/src/fork/forkRunEffect.js

@@ -0,0 +1,147 @@
+import { Effect, Metric } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { smithersBranches, smithersSnapshots } from "../schema.js";
+import { loadSnapshot } from "../snapshot/loadSnapshotEffect.js";
+import { parseSnapshot } from "../snapshot/parseSnapshot.js";
+import { runForksCreated } from "../runForksCreated.js";
+import { expandResetSet } from "./_helpers.js";
+/** @typedef {import("../BranchInfo.ts").BranchInfo} BranchInfo */
+/** @typedef {import("../ForkParams.ts").ForkParams} ForkParams */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("../snapshot/Snapshot.ts").Snapshot} Snapshot */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {ForkParams} params
+ * @returns {Effect.Effect<{ runId: string; branch: BranchInfo; snapshot: Snapshot }, SmithersError>}
+ */
+export function forkRun(adapter, params) {
+    return Effect.gen(function* () {
+        const { parentRunId, frameNo, inputOverrides, resetNodes, branchLabel, forkDescription } = params;
+        // 1. Load source snapshot
+        const source = yield* loadSnapshot(adapter, parentRunId, frameNo);
+        if (!source) {
+            return yield* Effect.fail(new SmithersError("SNAPSHOT_NOT_FOUND", `No snapshot found for run=${parentRunId} frame=${frameNo}`, { frameNo, runId: parentRunId }));
+        }
+        // 2. Create new run ID
+        const childRunId = crypto.randomUUID();
+        const ts = nowMs();
+        const parentRun = yield* Effect.tryPromise({
+            try: () => adapter.getRun(parentRunId),
+            catch: (cause) => toSmithersError(cause, "load parent run metadata", {
+                code: "DB_QUERY_FAILED",
+                details: { runId: parentRunId },
+            }),
+        });
+        // 3. Optionally override input and reset nodes
+        let nodesJson = source.nodesJson;
+        let inputJson = source.inputJson;
+        if (inputOverrides) {
+            const existingInput = JSON.parse(source.inputJson);
+            inputJson = JSON.stringify({ ...existingInput, ...inputOverrides });
+        }
+        if (resetNodes && resetNodes.length > 0) {
+            const parsed = parseSnapshot(source);
+            const keysToReset = expandResetSet(parsed.nodes, resetNodes);
+            const nodesArr = JSON.parse(source.nodesJson);
+            const updatedNodes = nodesArr.map((n) => {
+                const key = `${n.nodeId}::${n.iteration}`;
+                if (keysToReset.includes(key) || resetNodes.includes(n.nodeId)) {
+                    return { ...n, state: "pending", lastAttempt: null };
+                }
+                return n;
+            });
+            nodesJson = JSON.stringify(updatedNodes);
+        }
+        // 4. Insert snapshot for the child run at frame 0
+        const childSnapshot = {
+            runId: childRunId,
+            frameNo: 0,
+            nodesJson,
+            outputsJson: source.outputsJson,
+            ralphJson: source.ralphJson,
+            inputJson,
+            vcsPointer: source.vcsPointer,
+            workflowHash: source.workflowHash,
+            contentHash: source.contentHash,
+            createdAtMs: ts,
+        };
+        yield* Effect.tryPromise({
+            try: () => adapter.db
+                .insert(smithersSnapshots)
+                .values(childSnapshot)
+                .onConflictDoUpdate({
+                target: [smithersSnapshots.runId, smithersSnapshots.frameNo],
+                set: childSnapshot,
+            }),
+            catch: (cause) => toSmithersError(cause, "insert forked snapshot", {
+                code: "DB_WRITE_FAILED",
+                details: { frameNo: 0, runId: childRunId },
+            }),
+        });
+        if (parentRun) {
+            yield* Effect.tryPromise({
+                try: () => adapter.insertRun({
+                    runId: childRunId,
+                    parentRunId,
+                    workflowName: parentRun.workflowName,
+                    workflowPath: parentRun.workflowPath ?? null,
+                    workflowHash: source.workflowHash ?? parentRun.workflowHash ?? null,
+                    status: parentRun.status === "running" ? "failed" : parentRun.status,
+                    createdAtMs: ts,
+                    startedAtMs: null,
+                    finishedAtMs: parentRun.finishedAtMs ?? ts,
+                    heartbeatAtMs: null,
+                    runtimeOwnerId: null,
+                    cancelRequestedAtMs: null,
+                    hijackRequestedAtMs: null,
+                    hijackTarget: null,
+                    vcsType: parentRun.vcsType ?? null,
+                    vcsRoot: parentRun.vcsRoot ?? null,
+                    vcsRevision: source.vcsPointer ?? parentRun.vcsRevision ?? null,
+                    errorJson: null,
+                    configJson: parentRun.configJson ?? null,
+                }),
+                catch: (cause) => toSmithersError(cause, "insert forked run", {
+                    code: "DB_WRITE_FAILED",
+                    details: { runId: childRunId },
+                }),
+            });
+        }
+        // 5. Record branch relationship
+        const branch = {
+            runId: childRunId,
+            parentRunId,
+            parentFrameNo: frameNo,
+            branchLabel: branchLabel ?? null,
+            forkDescription: forkDescription ?? null,
+            createdAtMs: ts,
+        };
+        yield* Effect.tryPromise({
+            try: () => adapter.db
+                .insert(smithersBranches)
+                .values(branch)
+                .onConflictDoUpdate({
+                target: smithersBranches.runId,
+                set: branch,
+            }),
+            catch: (cause) => toSmithersError(cause, "insert branch", {
+                code: "DB_WRITE_FAILED",
+                details: { runId: childRunId },
+            }),
+        });
+        yield* Metric.increment(runForksCreated);
+        yield* Effect.logInfo("Run forked").pipe(Effect.annotateLogs({
+            parentRunId,
+            parentFrameNo: String(frameNo),
+            childRunId,
+            branchLabel: branchLabel ?? "",
+        }));
+        return { runId: childRunId, branch, snapshot: childSnapshot };
+    }).pipe(Effect.annotateLogs({
+        parentRunId: params.parentRunId,
+        parentFrameNo: String(params.frameNo),
+    }), Effect.withLogSpan("time-travel:fork-run"));
+}

package/src/fork/getBranchInfoEffect.js

@@ -0,0 +1,26 @@
+import { eq } from "drizzle-orm";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { smithersBranches } from "../schema.js";
+/** @typedef {import("../BranchInfo.ts").BranchInfo} BranchInfo */
+/** @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<BranchInfo | undefined, SmithersError>}
+ */
+export function getBranchInfo(adapter, runId) {
+    return Effect.tryPromise({
+        try: () => adapter.db
+            .select()
+            .from(smithersBranches)
+            .where(eq(smithersBranches.runId, runId))
+            .limit(1),
+        catch: (cause) => toSmithersError(cause, "get branch info", {
+            code: "DB_QUERY_FAILED",
+            details: { runId },
+        }),
+    }).pipe(Effect.map((rows) => rows[0]), Effect.annotateLogs({ runId }), Effect.withLogSpan("time-travel:get-branch-info"));
+}

package/src/fork/index.js

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import { forkRun as forkRunEffect } from "./forkRunEffect.js";
+import { getBranchInfo as getBranchInfoEffect } from "./getBranchInfoEffect.js";
+import { listBranches as listBranchesEffect } from "./listBranchesEffect.js";
+export { forkRunEffect, getBranchInfoEffect, listBranchesEffect, };
+
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("../BranchInfo.ts").BranchInfo} BranchInfo */
+/** @typedef {import("../ForkParams.ts").ForkParams} ForkParams */
+/** @typedef {import("../snapshot/Snapshot.ts").Snapshot} Snapshot */
+
+/**
+ * Fork a run at the given frame, returning the child run metadata.
+ *
+ * @param {SmithersDb} adapter
+ * @param {ForkParams} params
+ * @returns {Promise<{ runId: string; branch: BranchInfo; snapshot: Snapshot }>}
+ */
+export function forkRun(adapter, params) {
+    return Effect.runPromise(forkRunEffect(adapter, params));
+}
+/**
+ * List branches that were forked from the given parent run.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} parentRunId
+ * @returns {Promise<BranchInfo[]>}
+ */
+export function listBranches(adapter, parentRunId) {
+    return Effect.runPromise(listBranchesEffect(adapter, parentRunId));
+}
+/**
+ * Get the branch record for a run, if any.
+ *
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @returns {Promise<BranchInfo | undefined>}
+ */
+export function getBranchInfo(adapter, runId) {
+    return Effect.runPromise(getBranchInfoEffect(adapter, runId));
+}

package/src/fork/listBranchesEffect.js

@@ -0,0 +1,25 @@
+import { eq } from "drizzle-orm";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { smithersBranches } from "../schema.js";
+/** @typedef {import("../BranchInfo.ts").BranchInfo} BranchInfo */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} parentRunId
+ * @returns {Effect.Effect<BranchInfo[], SmithersError>}
+ */
+export function listBranches(adapter, parentRunId) {
+    return Effect.tryPromise({
+        try: () => adapter.db
+            .select()
+            .from(smithersBranches)
+            .where(eq(smithersBranches.parentRunId, parentRunId)),
+        catch: (cause) => toSmithersError(cause, "list branches", {
+            code: "DB_QUERY_FAILED",
+            details: { parentRunId },
+        }),
+    }).pipe(Effect.annotateLogs({ parentRunId }), Effect.withLogSpan("time-travel:list-branches"));
+}

package/src/hasRewindLock.js

@@ -0,0 +1,11 @@
+import { rewindLockStore } from "./rewindLockStore.js";
+
+/**
+ * Check whether a run currently holds a rewind lock.
+ *
+ * @param {string} runId
+ * @returns {boolean}
+ */
+export function hasRewindLock(runId) {
+  return rewindLockStore.has(runId);
+}