@visual-z/xeno 0.1.0

package/src/store/restore.ts

@@ -0,0 +1,302 @@
+/**
+ * Restoring the workspace to a node.
+ *
+ * This is where appendix H's argument becomes executable: reverting is not
+ * overwriting the present with the past, it is moving a cursor to another
+ * node. The nodes are untouched, so the cursor can move again -- which is
+ * why a restore here cannot produce the failure that made Zed's checkpoint
+ * restore an unanswered S1, where reverting destroyed both the files and the
+ * thread with no way back.
+ *
+ * WHY THIS DOES NOT REUSE readAncestry. That walk stops at a cut, because a
+ * handoff basis means the parent's events do not replay -- correct for
+ * context, catastrophic for files. A node whose ancestry crosses a cut would
+ * see only the snapshots after it, and applyRestore deletes whatever is not
+ * in its target, so restoring past a boundary would silently remove every
+ * file written before it. File history therefore always walks to the root,
+ * whatever each node declared about context.
+ */
+
+import { readNode, readManifest, digestNode, MAX_ANCESTRY_DEPTH, type Manifest } from "./log.ts";
+import type { LogEvent } from "../core/events.ts";
+import {
+  planRestore, applyRestore, scanWorkspace, DEFAULT_IGNORE,
+  type ScanDelta, type FileSet, type RestoreResult,
+} from "./workspace.ts";
+
+/**
+ * Where to move the workspace to.
+ *
+ * A bare node means the end of that node. `atEvent` names a snapshot inside
+ * it, which is what makes an ordinary undo possible: a node accumulates many
+ * turns, so without it the earliest reachable state is the end of the node
+ * and nothing in the node being worked in can be taken back.
+ */
+export type RestoreTarget = number | { node: number; atEvent?: string };
+
+/** One snapshot, kept separate from its neighbours so a turn can be addressed. */
+export type FileDelta = ScanDelta & { node: number; event: string };
+
+export type FileHistoryResult =
+  | { ok: true; deltas: FileDelta[] }
+  | { ok: false; error: string };
+
+/** One ancestor's contribution: its events, bounded by any fork point below it. */
+export interface NodeEvents {
+  node: number;
+  events: LogEvent[];
+}
+
+export type NodeHistoryResult =
+  | { ok: true; nodes: NodeEvents[] }
+  | { ok: false; error: string };
+
+export type PlanResult =
+  | { ok: true; files: FileSet; willWrite: string[]; willDelete: string[] }
+  | { ok: false; error: string };
+
+export type RestoreToNodeResult =
+  | ({ ok: true } & RestoreResult)
+  | { ok: false; error: string };
+
+/**
+ * Every snapshot delta from the root to `node`, in replay order.
+ *
+ * Two fields on the way up, treated oppositely, because they answer different
+ * questions:
+ *
+ *   `basis` says what the MODEL should see, and is ignored here. A cut
+ *   truncates the context walk; the files it wrote are still on disk.
+ *
+ *   `at_event` says where this node's history BEGINS in its parent, which is
+ *   a question about history, so it is obeyed. Ignoring it makes a rewind
+ *   restore the very file it was asked to undo -- the parent's later turns
+ *   would flow into a node that forked before them.
+ */
+/**
+ * Every ancestor's events, root-to-leaf, bounded by the fork points below.
+ *
+ * The one traversal both file history and turn history are built on. They
+ * have to agree about where a node's history begins, or a rewind would move
+ * the files to one point and the conversation to another.
+ */
+export async function readNodeHistory(
+  dir: string,
+  node: number,
+  manifest?: Manifest,
+  scope: "workspace" | "context" = "workspace",
+): Promise<NodeHistoryResult> {
+  const index = manifest ?? await readManifest(dir);
+  const chain: NodeEvents[] = [];
+  const seen = new Set<number>();
+  let current: number | null = node;
+  // Set by a child's parent pointer: this ancestor contributes only the
+  // events up to and including that one.
+  let cutoff: string | undefined;
+  let depth = 0;
+
+  while (current !== null) {
+    if (seen.has(current)) {
+      return {
+        ok: false,
+        error: `CYCLE: parent chain from node ${node} revisits node ${current}`,
+      };
+    }
+    seen.add(current);
+    if (depth++ >= MAX_ANCESTRY_DEPTH) {
+      return {
+        ok: false,
+        error: `TOO_DEEP: history of node ${node} exceeded ${MAX_ANCESTRY_DEPTH} nodes`,
+      };
+    }
+
+    const { header, events, corrupt } = await readNode(dir, current);
+    const sealed = index.nodes.find((n) => n.node === current);
+    if (sealed && sealed.sha256 !== await digestNode(dir, current)) {
+      return { ok: false, error: `INTEGRITY: node ${current} digest differs from its sealed record` };
+    }
+    if (header === null) {
+      return { ok: false, error: `MISSING_HEADER: node ${current} has no header line` };
+    }
+    if (corrupt.length > 0) {
+      return {
+        ok: false,
+        error: `CORRUPT: node ${current} has ${corrupt.length} unparsable line(s)`,
+      };
+    }
+
+    // The fork point is an event id in the node's whole stream, not a
+    // snapshot index: a turn that changed nothing writes no snapshot, so
+    // counting snapshots would land on the wrong turn.
+    let contributed = events;
+    if (cutoff !== undefined) {
+      const at = events.findIndex((e) => e.id === cutoff);
+      if (at === -1) {
+        // Refused rather than falling back to the whole node. The fallback is
+        // the silent form of the bug the cutoff exists to prevent: it would
+        // restore exactly the work the fork was made to leave behind.
+        return {
+          ok: false,
+          error: `NO_SUCH_EVENT: node ${current} has no event ${cutoff} (fork point reached from ${node})`,
+        };
+      }
+      contributed = events.slice(0, at + 1);
+    }
+
+    chain.push({ node: current, events: contributed });
+    cutoff = header.parent?.at_event;
+    // A fresh subagent inherits files, not the parent's observations. Context
+    // history crosses compaction boundaries but stops at an explicit new root.
+    current = scope === "context" && header.basis === "none" ? null : header.parent?.node ?? null;
+  }
+
+  chain.reverse();
+  return { ok: true, nodes: chain };
+}
+
+/**
+ * Every snapshot delta from the root to `node`, in replay order.
+ *
+ * Two fields on the way up, treated oppositely, because they answer different
+ * questions:
+ *
+ *   `basis` says what the MODEL should see, and is ignored here. A cut
+ *   truncates the context walk; the files it wrote are still on disk.
+ *
+ *   `at_event` says where this node's history BEGINS in its parent, which is
+ *   a question about history, so it is obeyed. Ignoring it makes a rewind
+ *   restore the very file it was asked to undo -- the parent's later turns
+ *   would flow into a node that forked before them.
+ *
+ * Kept one entry per snapshot rather than merged per node: merging is lossy
+ * in exactly the direction that matters, since the turns inside a node are
+ * the ones a person is most likely to want back.
+ */
+export async function readFileHistory(
+  dir: string,
+  node: number,
+  manifest?: Manifest,
+): Promise<FileHistoryResult> {
+  const history = await readNodeHistory(dir, node, manifest);
+  if (!history.ok) return { ok: false, error: history.error };
+
+  const deltas: FileDelta[] = [];
+  for (const n of history.nodes) {
+    for (const e of n.events) {
+      if (e.t !== "snapshot") continue;
+      deltas.push({
+        node: n.node, event: e.id,
+        added: { ...e.added }, changed: { ...e.changed }, removed: [...e.removed],
+      });
+    }
+  }
+  return { ok: true, deltas };
+}
+
+/**
+ * What a restore would do, without doing it.
+ *
+ * Separate from the restore because applyRestore deletes whatever is not in
+ * the target -- necessary, or the workspace would end up a mixture of two
+ * states, but destructive enough that a caller has to be able to look first.
+ */
+export async function planRestoreToNode(
+  dir: string,
+  target: RestoreTarget,
+  manifest?: Manifest,
+  root?: string,
+  ignore: readonly string[] = DEFAULT_IGNORE,
+): Promise<PlanResult> {
+  const { node, atEvent } = typeof target === "number" ? { node: target, atEvent: undefined } : target;
+  const history = await readNodeHistory(dir, node, manifest);
+  if (!history.ok) return { ok: false, error: history.error };
+
+  const deltas: FileDelta[] = [];
+  for (const n of history.nodes) {
+    // The cutoff is an id in the EVENT stream, not in the snapshot stream: a
+    // fork point is where a conversation was whole, which is the end of an
+    // exchange and usually not a snapshot at all. Cutting the events first
+    // and collecting snapshots after is what keeps the files and the
+    // conversation landing on the same point.
+    let events = n.events;
+    if (atEvent !== undefined && n.node === node) {
+      const at = events.findIndex((e) => e.id === atEvent);
+      if (at === -1) {
+        return { ok: false, error: `NO_SUCH_EVENT: node ${node} has no event ${atEvent}` };
+      }
+      events = events.slice(0, at + 1);
+    }
+    for (const e of events) {
+      if (e.t !== "snapshot") continue;
+      deltas.push({
+        node: n.node, event: e.id,
+        added: { ...e.added }, changed: { ...e.changed }, removed: [...e.removed],
+      });
+    }
+  }
+
+  const files = planRestore(deltas, node);
+  const willWrite = Object.keys(files).sort();
+  if (!root) return { ok: true, files, willWrite, willDelete: [] };
+
+  const current = await scanWorkspace(root, ignore);
+  if (!current.ok) return { ok: false, error: current.error };
+  const willDelete = Object.keys(current.files).filter((p) => !(p in files)).sort();
+  return { ok: true, files, willWrite, willDelete };
+}
+
+/**
+ * Moves the workspace to the state it had at `node`.
+ *
+ * Writes nothing to the log. The log is the truth and the workspace is a
+ * projection of it, so there is nothing to record: the nodes did not change,
+ * only which one is being projected. That is also what keeps this safe
+ * despite being irreversible in itself -- the previous cursor position is
+ * still a node, so the move can be made again in the other direction.
+ */
+export async function restoreToNode(
+  dir: string,
+  blobDir: string,
+  root: string,
+  target: RestoreTarget,
+  manifest?: Manifest,
+  ignore: readonly string[] = DEFAULT_IGNORE,
+): Promise<RestoreToNodeResult> {
+  const plan = await planRestoreToNode(dir, target, manifest ?? (await readManifest(dir)), root, ignore);
+  if (!plan.ok) return { ok: false, error: plan.error };
+  return { ok: true, ...(await applyRestorePlan(root, blobDir, plan.files, ignore, describeTarget(target))) };
+}
+
+/**
+ * Applies a plan that has already been computed.
+ *
+ * Split out so a caller holding a plan does not have to compute it twice.
+ * That is not only wasted work: a caller that re-planned inside the apply
+ * could never see the apply fail on its own, which turns its own "did the
+ * files move?" guard into unreachable code.
+ */
+export async function applyRestorePlan(
+  root: string,
+  blobDir: string,
+  files: FileSet,
+  ignore: readonly string[],
+  label: string,
+): Promise<RestoreResult> {
+  const result = await applyRestore(root, blobDir, files, ignore);
+  if (result.unrecoverable.length > 0) return result;
+  return {
+    ...result,
+    note:
+      `Workspace moved to ${label}. ` +
+      result.note +
+      " Other logged snapshots remain available. File versions never " +
+      "snapshotted cannot be reconstructed from the log.",
+  };
+}
+
+function describeTarget(target: RestoreTarget): string {
+  if (typeof target === "number") return `node ${target}`;
+  return target.atEvent === undefined
+    ? `node ${target.node}`
+    : `node ${target.node} as of snapshot ${target.atEvent}`;
+}