@vimhead.dev/norn-cli 0.1.0-tip.0

package/dist/internal/run-state.js

@@ -0,0 +1,323 @@
+// src/internal/run-state.ts
+import { mkdir as mkdir2, readdir, readFile } from "node:fs/promises";
+import { dirname as dirname2, isAbsolute, join, resolve } from "node:path";
+
+// ../core/src/errors.ts
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// src/internal/run-state.ts
+import { readRunLaunchRequest, readOptionalRunResumeRequest, RESUME_START_GRACE_MS } from "./launch-request.js";
+import { getRunLeaseHealth } from "./run-lease.js";
+
+// ../core/src/atomic-files.ts
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+async function writeJsonAtomically(path, value) {
+  await writeTextAtomically(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function writeTextAtomically(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  let existingMode;
+  try {
+    existingMode = (await stat(path)).mode & 511;
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+  }
+  const tmpPath = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmpPath, content, { encoding: "utf8", mode: existingMode });
+    if (existingMode !== void 0) await chmod(tmpPath, existingMode);
+    await rename(tmpPath, path);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+
+// src/internal/run-state.ts
+import { createRunFileCoordinator } from "@vimhead.dev/norn/files";
+import { runCurrentRoot } from "./run-store.js";
+var RUN_STATE_FILE_NAME = "run-state.json";
+var LEGACY_RUN_STATE_FILE_NAME = "runtime-state.json";
+function mergeInterruptedWorkflowParams(currentParams, params, fields) {
+  if (!isRecord(currentParams) || !isRecord(params)) return params;
+  if (fields) {
+    const unsupportedFields = Object.keys(params).filter((field) => !fields.includes(field));
+    if (unsupportedFields.length > 0) throw new Error(`Interrupted workflow params cannot update non-gate fields: ${unsupportedFields.join(", ")}`);
+  }
+  return { ...currentParams, ...params };
+}
+var RUN_STATE_VERSION = 1;
+var NornRunStateStore = class _NornRunStateStore {
+  path;
+  state;
+  files;
+  constructor(input) {
+    this.path = input.path;
+    this.state = input.state;
+    this.files = input.files;
+  }
+  static async create(runRoot, input) {
+    const now = input.startedAt;
+    const state = {
+      version: RUN_STATE_VERSION,
+      id: input.id,
+      name: input.name,
+      entrypointWorkflowId: input.entrypointWorkflowId,
+      workspace: input.workspace,
+      configOverride: input.configOverride,
+      status: "running",
+      current: input.current,
+      lastCompleted: null,
+      outcome: null,
+      failed: null,
+      startedAt: now,
+      updatedAt: now
+    };
+    const store = new _NornRunStateStore({ path: join(runCurrentRoot(runRoot), RUN_STATE_FILE_NAME), state, files: createRunFileCoordinator(runRoot) });
+    await store.write();
+    return store;
+  }
+  static async load(runRoot) {
+    const currentRoot = runCurrentRoot(runRoot);
+    const files = createRunFileCoordinator(runRoot);
+    const state = await files.withExclusiveLock(join(currentRoot, RUN_STATE_FILE_NAME), async (path) => parseNornRunState(await readRunStateFile({ path, legacyPath: join(currentRoot, LEGACY_RUN_STATE_FILE_NAME) })));
+    return new _NornRunStateStore({ path: join(currentRoot, RUN_STATE_FILE_NAME), state, files });
+  }
+  currentState() {
+    return this.state;
+  }
+  async startStep(step) {
+    await this.update({ status: "running", current: step, outcome: null, failed: null });
+  }
+  async completeWithNext(completedWorkflowId, next) {
+    await this.update({
+      status: "running",
+      current: next,
+      lastCompleted: { workflowId: completedWorkflowId, completedAt: (/* @__PURE__ */ new Date()).toISOString(), outcome: { type: "next", workflowId: next.workflowId } },
+      outcome: null,
+      failed: null
+    });
+  }
+  async completeRun(workflowId, metadata) {
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.update({
+      status: "completed",
+      current: null,
+      lastCompleted: { workflowId, completedAt, outcome: { type: "complete" } },
+      outcome: { workflowId, completedAt, status: "completed", metadata },
+      failed: null
+    });
+  }
+  async failRun(workflowId, metadata) {
+    const failedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.update({
+      status: "failed",
+      current: null,
+      lastCompleted: { workflowId, completedAt: failedAt, outcome: { type: "fail" } },
+      outcome: { workflowId, completedAt: failedAt, status: "failed", metadata },
+      failed: { workflowId, error: metadata.summary, metadata, failedAt }
+    });
+  }
+  async interruptCurrent(params, interruption) {
+    if (!this.state.current) throw new Error("Cannot interrupt run without current step");
+    await this.update({
+      status: "interrupted",
+      current: { ...this.state.current, params, interruption: { status: "pending", ...interruption } },
+      outcome: null,
+      failed: null
+    });
+  }
+  async prepareForResumeAfterRollback() {
+    if (!this.state.current) throw new Error("Cannot resume a checkpoint without a current step");
+    if (this.state.status === "interrupted") return;
+    if (this.state.status !== "running") throw new Error(`Cannot resume checkpoint with ${this.state.status} status`);
+    await this.update({ status: "pendingResume", outcome: null, failed: null });
+  }
+  async stopCurrent() {
+    if (!this.state.current) throw new Error("Cannot stop run without current step");
+    await this.update({ status: "stopped", outcome: null, failed: null });
+  }
+  async replaceCurrentParams(params) {
+    if (!this.state.current) throw new Error("Cannot resume run without current step");
+    await this.update({
+      status: "running",
+      current: { ...this.state.current, params, interruption: { ...this.state.current.interruption, status: "satisfied" } },
+      outcome: null,
+      failed: null
+    });
+  }
+  async failCurrent(errorOrMetadata) {
+    if (!this.state.current) throw new Error("Cannot fail run without current step");
+    const failedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const metadata = typeof errorOrMetadata === "string" ? { summary: errorOrMetadata } : errorOrMetadata;
+    await this.update({
+      status: "failed",
+      outcome: { workflowId: this.state.current.workflowId, completedAt: failedAt, status: "failed", metadata },
+      failed: { workflowId: this.state.current.workflowId, error: metadata.summary, metadata, failedAt }
+    });
+  }
+  async update(patch) {
+    await this.files.withExclusiveLock(this.path, async (path) => {
+      const current = parseNornRunState(await readRunStateFile({ path, legacyPath: join(dirname2(this.path), LEGACY_RUN_STATE_FILE_NAME) }));
+      const next = { ...current, ...patch, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await writeJsonAtomically(path, next);
+      this.state = next;
+    });
+  }
+  async write() {
+    await mkdir2(dirname2(this.path), { recursive: true });
+    await this.files.withExclusiveLock(this.path, (path) => writeJsonAtomically(path, this.state));
+  }
+};
+async function listRuns(sessionCwd) {
+  const runsRoot = join(sessionCwd, ".norn", "runs");
+  let entries;
+  try {
+    entries = await readdir(runsRoot, { withFileTypes: true });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return [];
+    throw error;
+  }
+  const runs = await Promise.all(entries.filter((entry) => entry.isDirectory()).map((entry) => readNornRunInfo(resolve(runsRoot, entry.name))));
+  return runs.filter((run) => run !== void 0).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+async function getRunInfo(runRoot) {
+  try {
+    const resumeRequest = await readOptionalRunResumeRequest(runRoot);
+    const state = parseNornRunState(await readRunStateJson(runCurrentRoot(runRoot)));
+    return {
+      version: state.version,
+      id: state.id,
+      name: state.name,
+      path: runRoot,
+      entrypointWorkflowId: state.entrypointWorkflowId,
+      currentWorkflowId: state.current?.workflowId,
+      status: resumeRequest ? "running" : state.status,
+      health: resumeRequest ? await getPendingResumeHealth(runRoot, resumeRequest.createdAt) : await runHealth(runRoot, state.status),
+      interruption: resumeRequest ? void 0 : runInterruption(state),
+      outcome: runOutcome(state),
+      failed: runFailure(state),
+      startedAt: state.startedAt,
+      updatedAt: state.updatedAt
+    };
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+    return getLaunchedRunInfo(runRoot);
+  }
+}
+async function resolveRunRoot(sessionCwd, run) {
+  for (const candidate of runRootCandidates(sessionCwd, run)) {
+    try {
+      if (await readNornRunInfo(candidate)) return candidate;
+    } catch (error) {
+      if (!isNodeError(error) && (!(error instanceof Error) || !error.message.includes("run state"))) throw error;
+    }
+  }
+  const runs = await listRuns(sessionCwd);
+  const match = runs.find((entry) => entry.id === run || entry.name === run || entry.path === run || entry.path.endsWith(`/${run}`));
+  if (!match) throw new Error(`Unknown run: ${run}`);
+  return match.path;
+}
+function runRootCandidates(sessionCwd, run) {
+  const candidates = [isAbsolute(run) ? run : resolve(sessionCwd, run)];
+  if (!isAbsolute(run)) candidates.push(resolve(sessionCwd, ".norn", "runs", run));
+  return Array.from(new Set(candidates));
+}
+async function getPendingResumeHealth(runRoot, requestedAt) {
+  const health = await getRunLeaseHealth(runRoot);
+  return health === "healthy" || Date.now() - Date.parse(requestedAt) < RESUME_START_GRACE_MS ? "healthy" : "unhealthy";
+}
+async function runHealth(runRoot, status) {
+  if (status !== "running") return "healthy";
+  return getRunLeaseHealth(runRoot);
+}
+async function readNornRunInfo(runRoot) {
+  try {
+    return await getRunInfo(runRoot);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function getLaunchedRunInfo(runRoot) {
+  const launchRequest = await readRunLaunchRequest(runRoot);
+  return {
+    version: launchRequest.version,
+    id: launchRequest.id,
+    name: launchRequest.name,
+    path: runRoot,
+    entrypointWorkflowId: launchRequest.workflowId,
+    currentWorkflowId: launchRequest.workflowId,
+    status: "running",
+    health: "healthy",
+    startedAt: launchRequest.createdAt,
+    updatedAt: launchRequest.createdAt
+  };
+}
+async function readRunStateJson(currentRoot) {
+  return readRunStateFile({ path: join(currentRoot, RUN_STATE_FILE_NAME), legacyPath: join(currentRoot, LEGACY_RUN_STATE_FILE_NAME) });
+}
+async function readRunStateFile(input) {
+  try {
+    return JSON.parse(await readFile(input.path, "utf8"));
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+    return JSON.parse(await readFile(input.legacyPath, "utf8"));
+  }
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function parseNornRunState(value) {
+  if (!value || typeof value !== "object") throw new Error("Invalid run state");
+  const state = value;
+  if (state.version !== RUN_STATE_VERSION) throw new Error(`Unsupported run state version: ${String(state.version)}`);
+  if (typeof state.id !== "string" || state.id.length === 0) throw new Error("Invalid run state id");
+  const normalizedState = state;
+  if (typeof normalizedState.name !== "string" || normalizedState.name.length === 0) normalizedState.name = state.id;
+  if (typeof normalizedState.entrypointWorkflowId !== "string" && typeof normalizedState.rootWorkflowId === "string") normalizedState.entrypointWorkflowId = normalizedState.rootWorkflowId;
+  if (typeof state.entrypointWorkflowId !== "string" || state.entrypointWorkflowId.length === 0) throw new Error("Invalid run state entrypoint workflow id");
+  if (typeof state.workspace !== "string" || state.workspace.length === 0) throw new Error("Invalid run state workspace");
+  if (state.status !== "running" && state.status !== "interrupted" && state.status !== "stopped" && state.status !== "pendingResume" && state.status !== "completed" && state.status !== "failed") throw new Error("Invalid run state status");
+  if (state.status === "interrupted") assertInterruptedNornRunState(state);
+  if (state.status === "stopped" || state.status === "pendingResume") assertResumableNornRunState(state);
+  if (typeof state.startedAt !== "string" || typeof state.updatedAt !== "string") throw new Error("Invalid run state timestamps");
+  return state;
+}
+function assertInterruptedNornRunState(state) {
+  if (!state.current) throw new Error("Invalid interrupted run current step");
+  const interruption = state.current.interruption;
+  if (!interruption || interruption.status !== "pending") throw new Error("Invalid run interruption");
+  if (typeof interruption.description !== "string" || interruption.description.length === 0) throw new Error("Invalid run interruption description");
+}
+function assertResumableNornRunState(state) {
+  if (!state.current) throw new Error("Invalid resumable run current step");
+}
+function runInterruption(state) {
+  if (state.status !== "interrupted" || !state.current?.interruption) return void 0;
+  return {
+    workflowId: state.current.workflowId,
+    params: state.current.params,
+    description: state.current.interruption.description ?? "",
+    fields: state.current.interruption.fields
+  };
+}
+function runOutcome(state) {
+  return state.outcome ?? void 0;
+}
+function runFailure(state) {
+  return state.failed ?? void 0;
+}
+export {
+  NornRunStateStore,
+  RUN_STATE_FILE_NAME,
+  getRunInfo,
+  listRuns,
+  mergeInterruptedWorkflowParams,
+  resolveRunRoot
+};

package/dist/internal/run-store.d.ts

@@ -0,0 +1,35 @@
+import type { NornRunCheckpoint } from "@vimhead.dev/norn";
+export declare function runCurrentRoot(runRoot: string): string;
+export declare class NornRunStore {
+    private readonly runRoot;
+    private readonly currentRoot;
+    private readonly storeRoot;
+    private constructor();
+    static initialize(root: string): Promise<NornRunStore>;
+    static open(root: string): Promise<NornRunStore>;
+    currentSnapshotRef(): Promise<string>;
+    snapshotCurrent(message: string): Promise<NornRunCheckpoint>;
+    restoreSnapshot(ref: string, prepare: ((stagedRunRoot: string) => Promise<void>) | undefined): Promise<void>;
+    restoreCurrentSnapshot(): Promise<void>;
+    listCheckpoints(): Promise<NornRunCheckpoint[]>;
+    private readCheckpointHistory;
+    assertWorkspaceCanBeSnapshotted(_workspace: string): Promise<void>;
+    private get objectsRoot();
+    private get snapshotsRoot();
+    private get refsRoot();
+    private get currentRefPath();
+    private get checkpointsPath();
+    private createCheckpoint;
+    private createSnapshot;
+    private snapshotEntries;
+    private collectSnapshotEntries;
+    private storeObject;
+    private restoreSnapshotManifest;
+    private materializeSnapshot;
+    private materializedPath;
+    private readSnapshot;
+    private snapshotPath;
+    private snapshotRelativePath;
+    private assertCheckpointPathMatchesId;
+    private objectPath;
+}

package/dist/internal/run-store.js

@@ -0,0 +1,314 @@
+// src/internal/run-store.ts
+import { createHash, randomUUID as randomUUID2 } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod as chmod2, lstat, mkdir as mkdir2, mkdtemp, readFile, readdir, readlink, rename as rename2, rm as rm2, symlink, utimes, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname2, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { gunzip, gzip } from "node:zlib";
+
+// ../core/src/errors.ts
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// ../core/src/atomic-files.ts
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+async function writeJsonAtomically(path, value) {
+  await writeTextAtomically(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function writeTextAtomically(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  let existingMode;
+  try {
+    existingMode = (await stat(path)).mode & 511;
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+  }
+  const tmpPath = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmpPath, content, { encoding: "utf8", mode: existingMode });
+    if (existingMode !== void 0) await chmod(tmpPath, existingMode);
+    await rename(tmpPath, path);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+
+// src/internal/run-store.ts
+var gzipBuffer = promisify(gzip);
+var gunzipBuffer = promisify(gunzip);
+var SNAPSHOT_VERSION = 1;
+var CURRENT_DIR_NAME = "current";
+var STORE_DIR_NAME = "store";
+var CHECKPOINTS_FILE_NAME = "checkpoints.json";
+function runCurrentRoot(runRoot) {
+  return join(runRoot, CURRENT_DIR_NAME);
+}
+var NornRunStore = class _NornRunStore {
+  constructor(runRoot) {
+    this.runRoot = runRoot;
+    this.currentRoot = runCurrentRoot(runRoot);
+    this.storeRoot = join(runRoot, STORE_DIR_NAME);
+  }
+  runRoot;
+  currentRoot;
+  storeRoot;
+  static async initialize(root) {
+    const runStore = new _NornRunStore(root);
+    await mkdir2(runStore.currentRoot, { recursive: true });
+    await mkdir2(runStore.objectsRoot, { recursive: true });
+    await mkdir2(runStore.snapshotsRoot, { recursive: true });
+    await mkdir2(runStore.refsRoot, { recursive: true });
+    return runStore;
+  }
+  static async open(root) {
+    const runStore = new _NornRunStore(root);
+    await access(runStore.currentRoot, constants.R_OK | constants.W_OK);
+    await access(runStore.storeRoot, constants.R_OK | constants.W_OK);
+    return runStore;
+  }
+  async currentSnapshotRef() {
+    return readFile(this.currentRefPath, "utf8").then((value) => value.trim());
+  }
+  async snapshotCurrent(message) {
+    const previous = await this.readCheckpointHistory();
+    const checkpoint = this.createCheckpoint(message, previous.checkpoints.length + 1);
+    const checkpoints = [...previous.checkpoints, checkpoint];
+    await this.createSnapshot(checkpoint, checkpoints);
+    await writeJsonAtomically(this.checkpointsPath, checkpoints);
+    try {
+      await writeTextAtomically(this.currentRefPath, `${checkpoint.id}
+`);
+    } catch (error) {
+      if (previous.content === void 0) await rm2(this.checkpointsPath, { force: true });
+      else await writeTextAtomically(this.checkpointsPath, previous.content);
+      throw error;
+    }
+    return checkpoint;
+  }
+  async restoreSnapshot(ref, prepare) {
+    const checkpoint = (await this.listCheckpoints()).find((entry) => entry.id === ref);
+    if (!checkpoint) throw new Error(`Unknown active run checkpoint: ${ref}`);
+    await this.restoreSnapshotManifest(await this.readSnapshot(checkpoint.id), prepare);
+  }
+  async restoreCurrentSnapshot() {
+    await this.restoreSnapshotManifest(await this.readSnapshot(await this.currentSnapshotRef()), void 0);
+  }
+  async listCheckpoints() {
+    return (await this.readCheckpointHistory()).checkpoints;
+  }
+  async readCheckpointHistory() {
+    try {
+      const content = await readFile(this.checkpointsPath, "utf8");
+      const checkpoints = parseNornRunCheckpoints(JSON.parse(content));
+      for (const checkpoint of checkpoints) this.assertCheckpointPathMatchesId(checkpoint);
+      return { checkpoints, content };
+    } catch (error) {
+      if (isNodeError(error) && error.code === "ENOENT") return { checkpoints: [] };
+      throw error;
+    }
+  }
+  async assertWorkspaceCanBeSnapshotted(_workspace) {
+  }
+  get objectsRoot() {
+    return join(this.storeRoot, "objects", "sha256");
+  }
+  get snapshotsRoot() {
+    return join(this.storeRoot, "snapshots");
+  }
+  get refsRoot() {
+    return join(this.storeRoot, "refs");
+  }
+  get currentRefPath() {
+    return join(this.refsRoot, "current");
+  }
+  get checkpointsPath() {
+    return join(this.currentRoot, CHECKPOINTS_FILE_NAME);
+  }
+  createCheckpoint(message, index) {
+    const id = `cp_${randomUUID2().replaceAll("-", "")}`;
+    return { id, path: this.snapshotRelativePath(id), index, message, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+  }
+  async createSnapshot(checkpoint, checkpoints) {
+    const entries = (await this.snapshotEntries(this.currentRoot)).filter((entry) => entry.path !== CHECKPOINTS_FILE_NAME);
+    const historyBytes = Buffer.from(`${JSON.stringify(checkpoints, null, 2)}
+`);
+    const historyHash = hashBuffer(historyBytes);
+    await this.storeObject(historyHash, historyBytes);
+    entries.push({ path: CHECKPOINTS_FILE_NAME, type: "file", sha256: historyHash, size: historyBytes.length, mode: 384, mtimeMs: Date.now(), compression: "gzip" });
+    entries.sort((left, right) => left.path.localeCompare(right.path));
+    const snapshot = {
+      version: SNAPSHOT_VERSION,
+      id: checkpoint.id,
+      path: checkpoint.path,
+      index: checkpoint.index,
+      message: checkpoint.message,
+      createdAt: checkpoint.createdAt,
+      entries
+    };
+    await writeJsonAtomically(this.snapshotPath(snapshot.id), snapshot);
+    return snapshot;
+  }
+  async snapshotEntries(root) {
+    const entries = [];
+    await this.collectSnapshotEntries(root, "", entries);
+    return entries.sort((left, right) => left.path.localeCompare(right.path));
+  }
+  async collectSnapshotEntries(absolutePath, snapshotPath, entries) {
+    const stat2 = await lstat(absolutePath);
+    if (stat2.isDirectory()) {
+      if (snapshotPath.length > 0) entries.push({ path: snapshotPath, type: "directory", mode: stat2.mode });
+      const children = await readdir(absolutePath, { withFileTypes: true });
+      for (const child of children.sort((left, right) => left.name.localeCompare(right.name))) {
+        await this.collectSnapshotEntries(join(absolutePath, child.name), joinSnapshotPath(snapshotPath, child.name), entries);
+      }
+      return;
+    }
+    if (stat2.isSymbolicLink()) {
+      entries.push({ path: snapshotPath, type: "symlink", target: await readlink(absolutePath) });
+      return;
+    }
+    if (!stat2.isFile()) return;
+    const bytes = await readFile(absolutePath);
+    const sha256 = hashBuffer(bytes);
+    await this.storeObject(sha256, bytes);
+    entries.push({ path: snapshotPath, type: "file", sha256, size: stat2.size, mode: stat2.mode, mtimeMs: stat2.mtimeMs, compression: "gzip" });
+  }
+  async storeObject(sha256, bytes) {
+    const path = this.objectPath(sha256);
+    try {
+      await access(path, constants.R_OK);
+      return;
+    } catch (error) {
+      if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+    }
+    await mkdir2(dirname2(path), { recursive: true });
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile2(tmpPath, await gzipBuffer(bytes));
+    await rename2(tmpPath, path);
+  }
+  async restoreSnapshotManifest(snapshot, prepare) {
+    const stagedRunRoot = await mkdtemp(join(this.runRoot, ".restore-"));
+    const stagedCurrent = runCurrentRoot(stagedRunRoot);
+    const previousCurrent = join(this.runRoot, `.previous-${randomUUID2()}`);
+    try {
+      await mkdir2(stagedCurrent);
+      await this.materializeSnapshot(snapshot, stagedCurrent);
+      await prepare?.(stagedRunRoot);
+      await rename2(this.currentRoot, previousCurrent);
+      try {
+        await rename2(stagedCurrent, this.currentRoot);
+      } catch (error) {
+        await rename2(previousCurrent, this.currentRoot);
+        throw error;
+      }
+      try {
+        await writeTextAtomically(this.currentRefPath, `${snapshot.id}
+`);
+      } catch (error) {
+        await rename2(this.currentRoot, stagedCurrent);
+        await rename2(previousCurrent, this.currentRoot);
+        throw error;
+      }
+      await rm2(previousCurrent, { recursive: true, force: true }).catch(() => void 0);
+    } finally {
+      await rm2(stagedRunRoot, { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+  async materializeSnapshot(snapshot, destination) {
+    const entriesByPath = /* @__PURE__ */ new Map();
+    for (const entry of snapshot.entries) {
+      this.materializedPath(destination, entry.path);
+      if (entriesByPath.has(entry.path)) throw new Error(`Duplicate snapshot path: ${entry.path}`);
+      entriesByPath.set(entry.path, entry);
+    }
+    for (const entry of snapshot.entries) {
+      let parent = dirname2(entry.path);
+      while (parent !== ".") {
+        if (entriesByPath.get(parent)?.type !== "directory") throw new Error(`Snapshot parent is not a directory: ${parent}`);
+        parent = dirname2(parent);
+      }
+      if (entry.type === "directory") await mkdir2(this.materializedPath(destination, entry.path), { recursive: true });
+    }
+    for (const entry of snapshot.entries) {
+      if (entry.type === "directory") continue;
+      const path = this.materializedPath(destination, entry.path);
+      if (entry.type === "symlink") {
+        await symlink(entry.target, path);
+        continue;
+      }
+      const bytes = await gunzipBuffer(await readFile(this.objectPath(entry.sha256)));
+      const actualSha256 = hashBuffer(bytes);
+      if (actualSha256 !== entry.sha256) throw new Error(`CAS object checksum mismatch: ${entry.sha256}`);
+      await writeFile2(path, bytes);
+      await chmod2(path, entry.mode);
+      await utimes(path, new Date(entry.mtimeMs), new Date(entry.mtimeMs));
+    }
+    for (const entry of [...snapshot.entries].reverse()) {
+      if (entry.type === "directory") await chmod2(this.materializedPath(destination, entry.path), entry.mode);
+    }
+  }
+  materializedPath(destination, snapshotPath) {
+    if (snapshotPath.length === 0 || isAbsolute(snapshotPath) || snapshotPath.split(/[\\/]/).some((part) => part === ".." || part === "." || part === "")) throw new Error(`Invalid snapshot path: ${snapshotPath}`);
+    const path = resolve(destination, ...snapshotPath.split("/"));
+    const pathFromCurrent = relative(destination, path);
+    if (pathFromCurrent === ".." || pathFromCurrent.startsWith(`..${sep}`)) throw new Error(`Snapshot path escapes current checkout: ${snapshotPath}`);
+    return path;
+  }
+  async readSnapshot(id) {
+    return parseRunSnapshotManifest(JSON.parse(await readFile(this.snapshotPath(id), "utf8")));
+  }
+  snapshotPath(id) {
+    return join(this.snapshotsRoot, `${id}.json`);
+  }
+  snapshotRelativePath(id) {
+    return relative(this.runRoot, this.snapshotPath(id));
+  }
+  assertCheckpointPathMatchesId(checkpoint) {
+    const expectedPath = this.snapshotRelativePath(checkpoint.id);
+    if (checkpoint.path !== expectedPath) throw new Error(`Run checkpoint path does not match id: ${checkpoint.id}`);
+  }
+  objectPath(sha256) {
+    return join(this.objectsRoot, sha256.slice(0, 2), sha256.slice(2, 4), `${sha256}.gz`);
+  }
+};
+function hashBuffer(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function joinSnapshotPath(parent, child) {
+  return parent.length === 0 ? child : `${parent}/${child}`;
+}
+function parseRunSnapshotManifest(value) {
+  if (!value || typeof value !== "object") throw new Error("Invalid run snapshot manifest");
+  const snapshot = value;
+  if (snapshot.version !== SNAPSHOT_VERSION) throw new Error(`Unsupported run snapshot version: ${String(snapshot.version)}`);
+  if (typeof snapshot.id !== "string" || snapshot.id.length === 0) throw new Error("Invalid run snapshot id");
+  if (typeof snapshot.index !== "number" || !Number.isInteger(snapshot.index) || snapshot.index < 1) throw new Error("Invalid run snapshot index");
+  if (typeof snapshot.message !== "string") throw new Error("Invalid run snapshot message");
+  if (typeof snapshot.createdAt !== "string") throw new Error("Invalid run snapshot timestamp");
+  if (!Array.isArray(snapshot.entries)) throw new Error("Invalid run snapshot entries");
+  return snapshot;
+}
+function parseNornRunCheckpoints(value) {
+  if (!Array.isArray(value)) throw new Error("Invalid run checkpoints");
+  return value.map(parseNornRunCheckpoint);
+}
+function parseNornRunCheckpoint(value) {
+  if (!value || typeof value !== "object") throw new Error("Invalid run checkpoint");
+  const checkpoint = value;
+  if (typeof checkpoint.id !== "string" || checkpoint.id.length === 0) throw new Error("Invalid run checkpoint id");
+  if (typeof checkpoint.path !== "string" || checkpoint.path.length === 0) throw new Error("Invalid run checkpoint path");
+  if (checkpoint.path.split(/[\\/]/).includes("..") || resolve(checkpoint.path) === checkpoint.path) throw new Error(`Invalid run checkpoint path: ${checkpoint.path}`);
+  if (typeof checkpoint.index !== "number" || !Number.isInteger(checkpoint.index) || checkpoint.index < 1) throw new Error("Invalid run checkpoint index");
+  if (typeof checkpoint.message !== "string") throw new Error("Invalid run checkpoint message");
+  if (typeof checkpoint.createdAt !== "string") throw new Error("Invalid run checkpoint timestamp");
+  return checkpoint;
+}
+export {
+  NornRunStore,
+  runCurrentRoot
+};