Skip to content

Write HTML. Render video. Built for agents.

53.6 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
import {
  type Dirent,
  type Stats,
  existsSync,
  lstatSync,
  statSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  realpathSync,
  rmSync,
} from "node:fs";
import { homedir } from "node:os";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import {
  DELETED_VERSION,
  fileContentVersion,
  hashOfVersion,
  hashVersion,
  onFileOverwritten,
  recordFileWriteReceipt,
} from "../helpers/fileVersion.js";
import { realFilePath } from "../helpers/safePath.js";
import {
  STUDIO_SIGNATURE_MANIFEST_PATHS,
  affectsProjectSignature,
  listProjectFiles,
} from "../helpers/projectSignature.js";
import { openBlobStore, readBlob, type BlobStore } from "./blobStore.js";
import { pruneGoneProjectHistoriesDaily } from "./pruneHistories.js";
import {
  ID_PATH,
  isRecordedFolder,
  sameFolder,
  projectHistoryId,
  readId,
  recordProject,
  type FolderIdentity,
} from "./historyId.js";
import { takeHistoryOwnership } from "./ownerLock.js";
import { writeHistoryState } from "./videoState.js";
import {
  START,
  baselineRecord,
  foldOldest,
  manifestAround,
  manifestAt,
  readLog,
  saveRecord,
  referencedHashes,
  stepTarget,
  undoneIds,
  writeLog,
  type HistoryEntry,
  type HistoryTarget,
  type HistoryEntrySide,
  type HistoryFileChange,
  type HistoryLog,
  type HistoryWho,
  type LogRecord,
  type Manifest,
} from "./historyLog.js";

/** Where hosts keep project histories unless told otherwise: outside every project, so no tidy-up takes one away. */
export const DEFAULT_HISTORY_ROOT = join(homedir(), ".cache", "hyperframes", "history");

export interface ProjectHistoryOptions {
  projectDir: string;
  /** Kept outside the project, so nothing tidying the project can take its history with it. */
  historyRoot: string;
  now?: () => number;
  /** Writes with no window open group into one entry until this long without another (default 2 s)... */
  quietMs?: number;
  /** ...or this long after the first (default 30 s). */
  maxGroupMs?: number;
  /** Past this many stored bytes the oldest unpinned entries are folded away (default 2 GB). */
  budgetBytes?: number;
  /** A sweep or commit that a watcher or timer started failed. */
  onError?: (error: unknown) => void;
  /** How long an open waits for another process to close the same history (default 5 s). */
  ownerWaitMs?: number;
  ownerUrl?: string;
  /** A CLI turn's window from an earlier open: writes since, within its idle limit, become the entry with its id. */
  closedWindow?: ClosedWindow;
  closedWindowAfterOwnership?: () => ClosedWindow | undefined;
  undoScope?: "own" | "everyone";
  pruneGoneProjectsBudgetMs?: number;
}

interface ClaimOptions {
  targets?: readonly HistoryTarget[];
  coalesceKey?: string;
  idleMs?: number;
  /** Per path, the version (fileContentVersion) the claimer overwrote: earlier changes stay their writer's. */
  overwrote?: Readonly<Record<string, string>>;
}

interface Writing {
  writeToken?: string;
}

export interface ClosedWindow {
  id: string;
  who: HistoryWho;
  label: string;
  startedAt: number;
  lastWriteAt: number;
  idleMs: number;
}

export const MAX_WINDOW_IDLE_MS = 10 * 60_000;

export const UNDO_MODES = ["just-this", "back-to-before", "keep-later-edits"] as const;
export type UndoMode = (typeof UNDO_MODES)[number];

export interface HistoryListItem extends HistoryEntry {
  pinned: boolean;
  undone: boolean;
}

export type HistoryResult =
  | { ok: true; entry: HistoryEntry | null }
  | { ok: false; conflict: { files: string[]; newer: string[] } };

export interface HistoryWindow {
  readonly id: string;
  readonly startedAt: number;
  /** Records everything written since the window opened as one entry (null when nothing changed); after the window
   * ended by itself or by flush, returns the entry it became. */
  close(): Promise<HistoryEntry | null>;
}

export interface ProjectHistory {
  readonly projectId: string;
  /** Writes until close() are one entry with the window's id; another writer or an operation meanwhile commits the
   * part so far first (fresh id), returned by close() if nothing else remained. Overlaps go to the newest. */
  beginWindow(
    who: HistoryWho,
    label: string,
    options?: { idleMs?: number; exclusive?: boolean },
  ): Promise<HistoryWindow>;
  /**
   * For a writer that records after writing (Studio): moves the uncommitted changes to `paths` into one entry of
   * `who`'s, each cut at the `overwrote` version so earlier parts stay their writer's. Same-key claims merge until
   * another key, idle, an operation, a window, or another write. Null when nothing was claimed or a drag nets to 0.
   */
  claim(
    who: HistoryWho,
    label: string,
    paths: readonly string[],
    options?: ClaimOptions,
  ): Promise<{ id: string } | null>;
  /** A watcher saw `path` change (project-relative or absolute). */
  noteChange(path: string): void;
  list(): HistoryListItem[];
  /** Cmd+Z (back) and Cmd+Shift+Z (forward) over `who`'s own and outside changes, or all (undoScope everyone). */
  step(direction: "back" | "forward", who: HistoryWho, options?: Writing): Promise<HistoryResult>;
  /** The entry `who`'s next step reverts, pending changes included, as of the last scan (a step scans first). */
  next(direction: "back" | "forward", who: HistoryWho): HistoryEntry | undefined;
  /** A file changed since returns a conflict; `mode` takes a choice (keep-later-edits: null when none is left). */
  undo(id: string, options: { who: HistoryWho; mode?: UndoMode } & Writing): Promise<HistoryResult>;
  /** Makes the files equal what they were right after `point` (an entry id, or START). */
  restore(point: string, who: HistoryWho, options?: Writing): Promise<HistoryEntry | null>;
  /** The files at `point` without writing anything: path to hash, read through readBlob. */
  peek(point: string): Record<string, string> | null;
  checkout(entryId: string, side: HistoryEntrySide, emptyDir: string): Promise<void>;
  readBlob(hash: string): Promise<Buffer>;
  pin(id: string, pinned: boolean): void;
  onEntry(listener: (entry: HistoryEntry) => void): () => void;
  /** Takes in every pending write and commits every open window and the outside group. */
  checkpoint(): Promise<void>;
  flush(): Promise<void>;
  /** True once another project stands at the folder's path: open that one's history instead. */
  replacedAtPath(): boolean;
  close(): Promise<void>;
}

const OUTSIDE: HistoryWho = { kind: "outside", name: "Outside" };
const OUTSIDE_LABEL = "Changed outside the app";

interface Tracked {
  hash: string;
  stat: string;
}

interface Group {
  targets?: HistoryTarget[];
  id: string;
  who: HistoryWho;
  label: string;
  startedAt: number;
  changes: Map<string, HistoryFileChange>;
  /** Windows only: the idle lifetime, its timer, the last write's time, and the entry it became once ended. */
  idleMs?: number;
  lastWriteAt?: number;
  idleTimer?: NodeJS.Timeout;
  entry?: HistoryEntry | null;
  parts?: Set<string>;
}

/**
 * A stat is only trusted once the file is older than any file system's timestamp tick (git's "racily clean"): a
 * same-size rewrite inside one tick keeps its size, mtime and ctime. "" is never trusted, so the file is re-hashed.
 */
const RACY_MS = 2000;
const statKey = (file: { size: number; mtimeMs: number; ctimeMs: number }, sweptAt: number) =>
  sweptAt - Math.max(file.mtimeMs, file.ctimeMs) < RACY_MS
    ? ""
    : `${file.size}:${file.mtimeMs}:${file.ctimeMs}`;

const MEDIA_LEDGER = ".media/manifest.jsonl";
const KEPT_HIDDEN_PATHS = new Set<string>([...STUDIO_SIGNATURE_MANIFEST_PATHS, MEDIA_LEDGER]);

/** A hidden name anywhere in a path (a tool's own record, .DS_Store) is nobody's work, except the kept ones above. */
function isHistoryPath(path: string): boolean {
  if (KEPT_HIDDEN_PATHS.has(path)) return true;
  return !path.split("/").some((segment) => segment.startsWith("."));
}

const logFileIn = (home: string) => join(home, "log.jsonl");

function listOf(log: HistoryLog): HistoryListItem[] {
  const undone = undoneIds(log.entries);
  return log.entries.map((entry) => ({
    ...entry,
    pinned: log.pins.has(entry.id),
    undone: undone.has(entry.id),
  }));
}

function peekOf(log: HistoryLog, point: string): Record<string, string> | null {
  const files = manifestAt(log, point);
  return files && Object.fromEntries(files);
}

function withoutHiddenPaths(log: HistoryLog): HistoryLog {
  for (const path of log.baseline.keys()) if (!isHistoryPath(path)) log.baseline.delete(path);
  for (const entry of log.entries)
    entry.files = entry.files.filter((file) => isHistoryPath(file.path));
  return log;
}

const historyFiles = (dir: string) =>
  listProjectFiles(dir).filter((file) => isHistoryPath(file.path));
type ListedFile = ReturnType<typeof listProjectFiles>[number];
const COPY_LATER_ABOVE_BYTES = 1024 ** 2;

const sameWho = (a: HistoryWho, b: HistoryWho) => a.kind === b.kind && a.name === b.name;

/** Cuts a change at the overwritten `at`: [kept before it, claimed after]; `at` unknown or not kept claims all. */
function splitAt(
  change: HistoryFileChange,
  at: string | undefined,
  kept: boolean,
): [HistoryFileChange | null, HistoryFileChange | null] {
  if (at === change.after) return [change, null];
  if (!at || at === change.before || !kept) return [null, change];
  return [
    { ...change, after: at },
    { ...change, before: at },
  ];
}

const isMissingFolder = (error: unknown) =>
  ["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "");

/** Removes a folder at `dir` that holds only empty folders (inTheWay checked), so a file can take its place. */
async function removeEmptyFolders(dir: string): Promise<void> {
  let entries: Dirent[];
  try {
    entries = await readdir(dir, { withFileTypes: true });
  } catch (error) {
    if (isMissingFolder(error)) return;
    throw error;
  }
  for (const entry of entries)
    if (entry.isDirectory()) await removeEmptyFolders(join(dir, entry.name));
  await rmdir(dir);
}

/** The first file or link under folder `dir` (project path `at`) not in `deleted`; links are not followed. */
function fileLeftIn(dir: string, at: string, deleted: ReadonlySet<string>): string | undefined {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const path = `${at}/${entry.name}`;
    const left = entry.isDirectory()
      ? fileLeftIn(join(dir, entry.name), path, deleted)
      : deleted.has(path)
        ? undefined
        : path;
    if (left) return left;
  }
  return undefined;
}

/** Whether the project's disk treats `A` and `a` as one name: its history-id file answers when upper-cased. */
function ignoresCase(dir: string): boolean {
  const self = statSync(join(dir, ID_PATH), { throwIfNoEntry: false });
  const other = statSync(join(dir, ID_PATH.toUpperCase()), { throwIfNoEntry: false });
  return self !== undefined && other?.ino === self.ino && other.dev === self.dev;
}

const blocks = (removed: string, added: string) =>
  added.startsWith(`${removed}/`) || removed.startsWith(`${added}/`);

/** A window takes a write within idleMs of its last one; past that it has ended, even before its timer commits it. */
const MAX_TIMER_MS = 2 ** 31 - 1;

const takesWrite = (window: Group, at: number) =>
  window.idleMs === undefined || at - (window.lastWriteAt ?? at) <= window.idleMs;

function chainBackFrom(
  byAfter: Map<string, string> | undefined,
  hash: string,
): Map<string, string> {
  const chain = new Map<string, string>();
  let at = hash;
  let prior = byAfter?.get(at);
  while (prior !== undefined && !chain.has(at)) {
    chain.set(at, prior);
    at = prior;
    prior = byAfter?.get(at);
  }
  return chain;
}

/** Files one change to a group; a later change to the same path keeps the group's first "before". */
function addChange(group: Group, path: string, before: string | null, after: string | null): void {
  const earlier = group.changes.get(path);
  const from = earlier ? earlier.before : before;
  if (from === after) group.changes.delete(path);
  else group.changes.set(path, { path, before: from, after });
}

const targetKey = (target: HistoryTarget) =>
  JSON.stringify([target.file, target.id, target.hfId, target.selector, target.selectorIndex]);

function keepTargetsOfItsFiles(entry: HistoryEntry): HistoryEntry {
  const targets = entry.targets?.filter((target) =>
    entry.files.some((file) => file.path === target.file),
  );
  if (targets?.length) entry.targets = targets;
  else delete entry.targets;
  return entry;
}

class Engine {
  readonly dir: string;
  readonly foldsCase: boolean;
  readonly folder: FolderIdentity & { dev: number };
  readonly home: string;
  log: HistoryLog = { baseline: new Map(), entries: [], pins: new Set() };
  tracked = new Map<string, Tracked>();
  windows: Group[] = [];
  outside: Group | null = null;
  /** A coalescing claim, open until another key, its idle timer, an operation, a window, or another write. */
  claimed: { group: Group; key: string; timer?: NodeJS.Timeout } | null = null;
  adopting = new Map<string, Promise<void>>();
  /** Per path and hash an API write left, the hash of the bytes it replaced, until walked or written past. */
  overwritten = new Map<string, Map<string, string>>();
  stopHearing: (() => void) | undefined;
  writeToken: string | undefined;
  quietTimer: NodeJS.Timeout | undefined;
  maxTimer: NodeJS.Timeout | undefined;
  notedTimer: NodeJS.Timeout | null = null;
  listeners = new Set<(entry: HistoryEntry) => void>();
  tail: Promise<unknown> = Promise.resolve();
  closed = false;
  closing: Promise<void> | undefined;

  constructor(
    readonly options: ProjectHistoryOptions,
    readonly projectId: string,
    readonly blobs: BlobStore,
  ) {
    this.dir = resolve(options.projectDir);
    this.home = join(options.historyRoot, projectId);
    this.foldsCase = ignoresCase(this.dir);
    const folder = statSync(this.dir, { throwIfNoEntry: false });
    // Checked after the ownership wait, so a folder swapped for a copy meanwhile is refused.
    if (!folder || readId(this.dir) !== projectId || !isRecordedFolder(this.home, folder))
      throw this.replaced();
    this.folder = { dev: folder.dev, ino: folder.ino, birthtimeMs: folder.birthtimeMs };
  }

  /** A path as the project's disk compares names: folded where `A` and `a` are one name. */
  nameKey(path: string): string {
    return this.foldsCase ? path.toLowerCase() : path;
  }

  get logFile() {
    return logFileIn(this.home);
  }

  now(): number {
    return (this.options.now ?? Date.now)();
  }

  /** One operation at a time, in order: sweeps, windows and undos never interleave. */
  queue<T>(task: () => Promise<T>): Promise<T> {
    if (this.closed)
      return Promise.reject(new HistoryClosedError("This project's history is closed."));
    const run = this.tail.then(async () => {
      try {
        return await task();
      } finally {
        if (this.whereFolder() === "here") {
          await writeHistoryState(
            this.dir,
            this.projectId,
            this.home,
            this.log.entries,
            this.manifest(),
            manifestAt(this.log, this.log.entries.at(-1)?.id ?? START) ?? new Map(),
          ).catch((error) => this.options.onError?.(error));
        }
      }
    });
    this.tail = run.catch(() => undefined);
    return run;
  }

  /** Another project if the folder or its id changed, or the id is gone: a recreated folder may reuse the inode. */
  whereFolder(): "here" | "gone" | "replaced" {
    const now = statSync(this.dir, { throwIfNoEntry: false });
    if (!now) return "gone";
    const same = now.dev === this.folder.dev && sameFolder(now, this.folder);
    return same && readId(this.dir) === this.projectId ? "here" : "replaced";
  }

  assertWritable(): void {
    const folder = this.whereFolder();
    if (folder === "gone") throw new Error(`The project folder is gone: ${this.dir}`);
    if (folder === "replaced") throw this.replaced();
  }

  persistLog(record?: LogRecord): void {
    if (record) saveRecord(this.logFile, this.log, record);
    else writeLog(this.logFile, this.log);
    if (!existsSync(join(this.home, "project.json")))
      recordProject(this.home, this.dir, this.folder);
  }

  replaced(): HistoryClosedError {
    return new HistoryClosedError(`${this.dir} is now another project.`);
  }

  assertOpen(): void {
    if (this.closed) throw new HistoryClosedError("This project's history is closed.");
    if (this.whereFolder() === "replaced") throw this.replaced();
  }

  async start(): Promise<void> {
    const log = readLog(this.logFile, (line) =>
      this.options.onError?.(
        new Error(`History log line ${line} could not be read and was skipped.`),
      ),
    );
    if (!log) return this.firstOpen();
    this.log = withoutHiddenPaths(log);
    if (!this.log.keepsLedger) await this.takeInUnnamedLedger();
    const cache = this.readStatCache();
    const last = this.log.entries.at(-1)?.id ?? START;
    for (const [path, hash] of manifestAt(this.log, last) ?? []) {
      const cached = cache.get(path);
      this.tracked.set(path, { hash, stat: cached?.hash === hash ? cached.stat : "" });
    }
    const left = this.readAdopting();
    const unadopted = (file: { path: string }) =>
      left.has(file.path) && !this.tracked.has(file.path);
    this.adoptMediaInBackground(historyFiles(this.dir).filter(unadopted), this.now());
    // What changed while the project was closed is one outside entry, or the closed window's.
    this.reopenClosedWindow();
    await this.settleAll();
  }

  hearWrites(): void {
    const realDir = realFilePath(this.dir);
    this.stopHearing = onFileOverwritten((absPath, version, bytes) => {
      const after = hashOfVersion(version);
      if (!after || !affectsProjectSignature(realDir, absPath)) return;
      const replaced = hashOfVersion(fileContentVersion(bytes));
      if (!replaced || replaced === after) return;
      const path = relative(realDir, absPath).split(sep).join("/");
      if (!isHistoryPath(path)) return;
      // One chain per file, a new Map per write (forgetWritesBefore checks identity); off-chain notes were overwritten.
      this.overwritten.set(
        path,
        chainBackFrom(this.overwritten.get(path), replaced).set(after, replaced),
      );
      this.queue(async () => {
        if (!this.blobs.has(replaced)) await this.storeBytes(bytes);
      }).catch((error) => this.options.onError?.(error));
    });
  }

  async storeBytes(bytes: string | Uint8Array): Promise<void> {
    const staged = join(this.home, `overwrote-${randomUUID()}`);
    await mkdir(this.home, { recursive: true });
    await writeFile(staged, bytes);
    try {
      await this.blobs.put(staged);
    } finally {
      await rm(staged, { force: true });
    }
  }

  /** Read at a state no API write left, with no write heard since `heard`: no walk passes it, so forget the rest. */
  forgetWritesBefore(
    path: string,
    hash: string | null,
    heard: Map<string, string> | undefined,
  ): void {
    if (this.overwritten.get(path) === heard && !(hash && heard?.has(hash)))
      this.overwritten.delete(path);
  }

  reopenClosedWindow(): void {
    const closed = this.options.closedWindow;
    if (!closed || this.log.entries.some((entry) => entry.id === closed.id)) return;
    const { id, who, label, startedAt, lastWriteAt, idleMs } = closed;
    this.windows.push({ id, who, label, startedAt, lastWriteAt, idleMs, changes: new Map() });
  }

  async takeInUnnamedLedger(): Promise<void> {
    const named = (path: string) =>
      this.log.entries.some((entry) => entry.files.some((file) => file.path === path));
    const listed = () => historyFiles(this.dir).some((file) => file.path === MEDIA_LEDGER);
    const hash =
      this.log.baseline.has(MEDIA_LEDGER) || named(MEDIA_LEDGER) || !listed()
        ? null
        : await this.storeIfPresent(MEDIA_LEDGER);
    if (hash !== null) this.log.baseline.set(MEDIA_LEDGER, hash);
    this.log.keepsLedger = true;
    this.persistLog();
  }

  async firstOpen(): Promise<void> {
    const sweptAt = this.now();
    const files = historyFiles(this.dir);
    for (const file of files.filter((file) => file.size <= COPY_LATER_ABOVE_BYTES)) {
      const hash = await this.storeIfPresent(file.path);
      if (this.whereFolder() !== "here") throw this.replaced();
      if (hash !== null) this.tracked.set(file.path, { hash, stat: statKey(file, sweptAt) });
    }
    this.log.baseline = this.manifest();
    this.log.keepsLedger = true;
    this.persistLog();
    this.saveStatCache();
    this.adoptMediaInBackground(
      files.filter((file) => file.size > COPY_LATER_ABOVE_BYTES),
      sweptAt,
    );
  }

  adoptMediaInBackground(files: ListedFile[], sweptAt: number): void {
    let copied = Promise.resolve();
    for (const file of files) {
      copied = copied.then(() => this.adopt(file, sweptAt));
      this.adopting.set(file.path, copied);
    }
    this.saveAdopting();
  }

  saveAdopting(): void {
    const file = join(this.home, "adopting.json");
    if (!this.adopting.size) return rmSync(file, { force: true });
    mkdirSync(this.home, { recursive: true });
    replaceFileAtomically(file, JSON.stringify([...this.adopting.keys()]), 0o644);
  }

  async adopt(file: ListedFile, sweptAt: number) {
    try {
      if (this.whereFolder() !== "here") return;
      const stored = await this.storeIfPresent(file.path);
      await this.queue(async () => {
        // Still named for the next open until recorded, so a failed record is never logged as added.
        await this.recordAdopted(file, sweptAt, stored);
        this.adopting.delete(file.path);
        this.saveAdopting();
      });
    } catch (error) {
      if (!(error instanceof HistoryClosedError)) this.options.onError?.(error);
    }
  }

  async recordAdopted(file: ListedFile, sweptAt: number, stored: string | null) {
    if (stored === null || this.whereFolder() !== "here") return;
    // A prune that ran while this copy waited for the queue may have taken its bytes.
    const hash = this.blobs.has(stored) ? stored : await this.storeIfPresent(file.path);
    if (hash === null) return;
    const change = { path: file.path, before: null, after: hash };
    const found = this.overwrittenBy(change, undefined, new Set());
    const start = found && this.blobs.has(found) ? found : hash;
    this.tracked.set(file.path, { hash, stat: statKey(file, sweptAt) });
    this.log.baseline.set(file.path, start);
    if (start !== hash) addChange(this.outsideGroup(), file.path, start, hash);
    this.persistLog(baselineRecord(this.log));
    this.saveStatCache();
  }

  manifest(): Manifest {
    return new Map([...this.tracked].map(([path, file]) => [path, file.hash]));
  }

  readStatCache(): Map<string, Tracked> {
    try {
      const files = JSON.parse(readFileSync(join(this.home, "stat.json"), "utf-8"));
      return new Map(Object.entries(files as Record<string, Tracked>));
    } catch {
      return new Map();
    }
  }

  readAdopting(): Set<string> {
    try {
      return new Set(
        JSON.parse(readFileSync(join(this.home, "adopting.json"), "utf-8")) as string[],
      );
    } catch {
      return new Set();
    }
  }

  saveStatCache(): void {
    const files = JSON.stringify(Object.fromEntries(this.tracked));
    mkdirSync(this.home, { recursive: true });
    replaceFileAtomically(join(this.home, "stat.json"), files, 0o644);
  }

  /**
   * Takes in every write since the last sweep and files each change to its writer. ponytail: always the whole
   * project (a stat per file, a hash only when the stat moved); per-path sweeps if projects reach tens of thousands.
   */
  async sweep(): Promise<void> {
    // A folder moved or removed was not emptied, and another project at its path is none of this history's.
    if (this.whereFolder() !== "here") return;
    const sweptAt = this.now();
    const changedAt = (file: { mtimeMs: number; ctimeMs: number }) =>
      Math.min(sweptAt, Math.max(file.mtimeMs, file.ctimeMs));
    const seen = historyFiles(this.dir).filter((file) => !this.adopting.has(file.path));
    const heard = new Map(this.overwritten);
    const present = new Set(seen.map((file) => file.path));
    const removed = [...this.tracked.keys()]
      .filter((path) => !present.has(path))
      .map((path) => {
        const standing = this.standingAt(path);
        return { at: standing ? changedAt(standing.stat) : sweptAt, path, file: null };
      });
    // A file in the way of a removal (a/b over file a, or the reverse) appeared no earlier than that removal.
    const appearedAt = (file: (typeof seen)[number]) =>
      Math.max(
        changedAt(file),
        ...removed
          .filter((gone) => blocks(this.nameKey(gone.path), this.nameKey(file.path)))
          .map((gone) => gone.at),
      );
    const events = [
      ...removed,
      ...seen.map((file) => ({ at: appearedAt(file), path: file.path, file })),
    ].sort((a, b) => a.at - b.at);
    let changed = false;
    for (const { at, path, file } of events) {
      if (file) {
        changed = (await this.observe(path, statKey(file, sweptAt), at)) || changed;
        continue;
      }
      const known = this.tracked.get(path)!;
      this.tracked.delete(path);
      this.forgetWritesBefore(path, null, heard.get(path));
      await this.record(path, known.hash, null, at);
      changed = true;
    }
    if (changed) this.saveStatCache();
  }

  /** The file's hash once copied in; null when it was removed before the copy (the next sweep records that). */
  async storeIfPresent(path: string): Promise<string | null> {
    try {
      return await this.blobs.put(join(this.dir, path));
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
      throw error;
    }
  }

  async observe(path: string, stat: string, at: number): Promise<boolean> {
    const known = this.tracked.get(path) ?? { hash: null, stat: null };
    if (stat && known.stat === stat) return false;
    const heard = this.overwritten.get(path);
    const hash = await this.storeIfPresent(path);
    if (hash === null || this.whereFolder() !== "here") return false;
    this.tracked.set(path, { hash, stat });
    this.forgetWritesBefore(path, hash, heard);
    if (known.hash !== hash) await this.record(path, known.hash, hash, at);
    return known.hash !== hash || known.stat !== stat;
  }

  async record(
    path: string,
    before: string | null,
    after: string | null,
    at: number,
  ): Promise<void> {
    const endedBeforeThisWrite = this.windows.filter((open) => !takesWrite(open, at));
    if (endedBeforeThisWrite.length) await this.commitOutside();
    for (const window of endedBeforeThisWrite) await this.endWindow(window);
    const window = this.windows.at(-1);
    if (window) this.touch(window, at);
    addChange(window ?? this.outsideGroup(), path, before, after);
  }

  /** ponytail: another's write between Studio's write and its sweep folds into Studio's entry (per-write tokens). */
  async claimNow(
    who: HistoryWho,
    label: string,
    paths: readonly string[],
    { coalesceKey, idleMs, overwrote = {}, targets = [] }: ClaimOptions,
  ): Promise<{ id: string } | null> {
    await this.sweep();
    const taken = await this.takeClaimed(who, paths, overwrote);
    if (!taken.length) return this.claimNothing(coalesceKey);
    const held = this.heldFor(coalesceKey, taken);
    if (!held) await this.commitClaim();
    await this.commitPending();
    const group = held ?? this.newGroup(who, label);
    for (const change of taken) addChange(group, change.path, change.before, change.after);
    this.addTargets(group, targets);
    if (coalesceKey) return this.holdClaim(group, coalesceKey, idleMs);
    const entry = await this.commit(group);
    return entry && { id: entry.id };
  }

  addTargets(group: Group, targets: readonly HistoryTarget[]): void {
    const unique = new Map((group.targets ?? []).map((target) => [targetKey(target), target]));
    for (const target of targets) {
      const normalized = { ...target, file: this.logPath(target.file) };
      if (group.changes.has(normalized.file)) unique.set(targetKey(normalized), normalized);
    }
    group.targets = [...unique.values()];
  }

  /** A claim that took nothing still ends a held claim under another key. */
  async claimNothing(coalesceKey: string | undefined): Promise<null> {
    if (coalesceKey !== this.claimed?.key) await this.commitClaim();
    return null;
  }

  /** Commits every other writer's pending changes, oldest first; open windows stay open. */
  async commitPending(): Promise<void> {
    await this.commitOutside();
    for (const window of [...this.windows])
      if (window.changes.size) await this.commitCut(window, [...window.changes.keys()]);
  }

  pendingElsewhere(): boolean {
    return (
      Boolean(this.outside?.changes.size) || this.windows.some((open) => open.changes.size > 0)
    );
  }

  /** The held claim `taken` continues: same key, each file from its own last change, no held file changed since. */
  heldFor(key: string | undefined, taken: readonly HistoryFileChange[]): Group | null {
    const group =
      key && this.claimed?.key === key && !this.pendingElsewhere() ? this.claimed.group : null;
    const after = (path: string, before: string | null) => {
      const own = group?.changes.get(path);
      return own ? own.after : before;
    };
    const takenPaths = new Set(taken.map((change) => change.path));
    const untouched = (change: HistoryFileChange) =>
      takenPaths.has(change.path) || (this.tracked.get(change.path)?.hash ?? null) === change.after;
    return group &&
      taken.every((change) => after(change.path, change.before) === change.before) &&
      [...group.changes.values()].every(untouched)
      ? group
      : null;
  }

  logPath(path: string): string {
    return relative(this.dir, resolve(this.dir, path)).split(sep).join("/");
  }

  /** Takes `paths`' uncommitted changes from others, cut at what `who` overwrote. */
  async takeClaimed(
    who: HistoryWho,
    paths: readonly string[],
    overwrote: Readonly<Record<string, string>>,
  ): Promise<HistoryFileChange[]> {
    const wanted = new Set(paths.map((path) => this.logPath(path)));
    const at = new Map(
      Object.entries(overwrote).map(([path, version]) => [
        this.logPath(path),
        hashOfVersion(version),
      ]),
    );
    const others = this.windows.filter((open) => !sameWho(open.who, who));
    const groups = this.outside ? [this.outside, ...others] : others;
    const hits = groups.flatMap((group) =>
      [...group.changes.values()]
        .filter((change) => wanted.has(change.path))
        .map((change) => ({ group, change })),
    );
    const cuts: Array<string | undefined> = [];
    const walked = hits.map(() => new Set<string>());
    for (const [i, { change }] of hits.entries()) {
      const told = at.get(change.path);
      cuts.push(this.overwrittenBy(change, told, walked[i]!) ?? told);
    }
    hits.forEach(({ change }, i) => this.forgetOverwritten(change.path, walked[i]!));
    return hits.flatMap(({ group, change }, i) => this.cutOut(group, change, cuts[i]) ?? []);
  }

  /** Walks the server's writes back from `change.after` to the stored bytes they replaced. */
  overwrittenBy(change: HistoryFileChange, told: string | undefined, seen: Set<string>) {
    let found: string | undefined;
    for (let hash = change.after; hash; ) {
      // A loop (X, Y, back to X) says nothing about what was there first: the client's word stands.
      if (seen.has(hash)) return undefined;
      seen.add(hash);
      const replaced = this.overwritten.get(change.path)?.get(hash);
      if (replaced === undefined) break;
      found = hash = replaced;
      if (hash === change.before || hash === told) return hash;
    }
    return found;
  }

  forgetOverwritten(path: string, hashes: Iterable<string>): void {
    const byAfter = this.overwritten.get(path);
    for (const hash of hashes) byAfter?.delete(hash);
    if (byAfter?.size === 0) this.overwritten.delete(path);
  }

  cutOut(group: Group, change: HistoryFileChange, cut: string | undefined) {
    const [kept, claimed] = splitAt(change, cut, cut !== undefined && this.blobs.has(cut));
    group.changes.delete(change.path);
    if (kept) group.changes.set(kept.path, kept);
    return claimed;
  }

  /** Commits the window's cut `paths` as their own entry, other files staying: a window holds one change per file,
   * so the writer's next write to a cut file would otherwise span the claimer's edit. */
  async commitCut(window: Group, paths: readonly string[]): Promise<void> {
    const part = { ...this.newGroup(window.who, window.label), startedAt: window.startedAt };
    for (const path of paths) {
      part.changes.set(path, window.changes.get(path)!);
      window.changes.delete(path);
    }
    (window.parts ??= new Set()).add(part.id);
    window.entry = await this.commit(part);
  }

  holdClaim(
    group: Group,
    key: string,
    idleMs = this.options.quietMs ?? 2000,
  ): { id: string } | null {
    clearTimeout(this.claimed?.timer);
    const timer = Number.isFinite(idleMs)
      ? setTimeout(() => this.background(() => this.commitClaim()), idleMs)
      : undefined;
    timer?.unref?.();
    group.lastWriteAt = this.now();
    this.claimed = { group, key, timer };
    return group.changes.size ? { id: group.id } : null;
  }

  async commitClaim(): Promise<void> {
    const held = this.claimed;
    this.claimed = null;
    if (!held) return;
    clearTimeout(held.timer);
    await this.commit(held.group);
  }

  outsideGroup(): Group {
    const { quietMs = 2000, maxGroupMs = 30_000 } = this.options;
    const closeIn = (ms: number) => {
      const timer = setTimeout(() => this.background(() => this.commitOutside()), ms);
      timer.unref?.();
      return timer;
    };
    if (!this.outside) {
      this.outside = this.newGroup(OUTSIDE, OUTSIDE_LABEL);
      this.maxTimer = closeIn(maxGroupMs);
    }
    clearTimeout(this.quietTimer);
    this.quietTimer = closeIn(quietMs);
    return this.outside;
  }

  newGroup(who: HistoryWho, label: string): Group {
    return { id: randomUUID(), who, label, startedAt: this.now(), changes: new Map() };
  }

  async commitOutside(): Promise<void> {
    if (this.outside?.changes.size) await this.commitClaim();
    clearTimeout(this.quietTimer);
    clearTimeout(this.maxTimer);
    const group = this.outside;
    this.outside = null;
    if (group) await this.commit(group);
  }

  async commit(group: Group, extra: Partial<HistoryEntry> = {}): Promise<HistoryEntry | null> {
    const undoesEmptied =
      this.log.entries.find((entry) => entry.id === extra.undoes)?.files.length === 0;
    if (!group.changes.size && !undoesEmptied) return null;
    const pending = this.pendingEntry(group);
    const endedAt = Math.max(pending.endedAt, this.log.entries.at(-1)?.endedAt ?? 0);
    const entry = keepTargetsOfItsFiles({ ...pending, endedAt, ...extra });
    this.log.entries.push(entry);
    try {
      this.persistLog({ type: "entry", entry });
    } catch (error) {
      this.log.entries.pop();
      throw error;
    }
    for (const listener of this.listeners) listener(entry);
    for (const change of group.changes.values()) {
      const walked = new Set<string>();
      this.overwrittenBy(change, undefined, walked);
      this.forgetOverwritten(change.path, walked);
    }
    await this.keepWithinBudget();
    return entry;
  }

  /** Stored bytes beyond what the current files need: a project larger than the budget still keeps its history. */
  historyBytes(): number {
    let current = 0;
    for (const hash of new Set([...this.tracked.values()].map((file) => file.hash)))
      current += this.blobs.size(hash);
    return this.blobs.bytes() - current;
  }

  async keepWithinBudget(): Promise<void> {
    const budget = this.options.budgetBytes ?? 2 * 1024 ** 3;
    let folded = false;
    while (this.historyBytes() > budget) {
      await this.blobs.prune(
        new Set([
          ...referencedHashes(this.log, this.manifest()),
          ...this.pendingHashes(),
          ...[...this.overwritten.values()].flatMap((byAfter) => [...byAfter.values()]),
        ]),
      );
      if (this.historyBytes() <= budget || !foldOldest(this.log)) break;
      folded = true;
    }
    if (folded) this.persistLog();
  }

  /** Hashes only pending changes point at yet, such as a claim's stored cut. */
  pendingHashes(): string[] {
    const changes = [...this.windows, this.outside, this.claimed?.group].flatMap((group) => [
      ...(group?.changes.values() ?? []),
    ]);
    return changes
      .flatMap((change) => [change.before, change.after])
      .filter((hash): hash is string => hash !== null);
  }

  /** Before an operation or a window: every write is filed and every pending change committed, in write order. */
  async settle(): Promise<void> {
    await this.sweep();
    await this.commitClaim();
    await this.commitPending();
  }

  /** A watcher saw a write: one sweep per burst takes it in (a deleted folder is reported by its name alone). */
  noteChange(path: string): void {
    const absolute = resolve(this.dir, path);
    if (this.notedTimer || !affectsProjectSignature(this.dir, absolute)) return;
    if (!isHistoryPath(relative(this.dir, absolute).split(sep).join("/"))) return;
    this.notedTimer = setTimeout(() => {
      this.notedTimer = null;
      this.background(() => this.sweep());
    }, 20);
    this.notedTimer.unref?.();
  }

  background(task: () => Promise<unknown>): void {
    this.queue(task).catch((error) => {
      if (!(error instanceof HistoryClosedError)) this.options.onError?.(error);
    });
  }

  beginWindow(
    who: HistoryWho,
    label: string,
    idleMs: number,
    exclusive = false,
  ): Promise<HistoryWindow> {
    return this.queue(async () => {
      // Writes before the window opened are not this writer's, and are logged before it.
      await this.settle();
      const at = this.now();
      if (exclusive) {
        const blocking = this.windows.find(
          (open) => !sameWho(open.who, who) && takesWrite(open, at),
        );
        if (blocking)
          throw new Error(`${blocking.who.name}'s turn is open; it has to end before yours begins`);
        for (const open of [...this.windows])
          if (!takesWrite(open, at) || sameWho(open.who, who)) await this.endWindow(open);
      }
      const window = { ...this.newGroup(who, label), idleMs };
      this.windows.push(window);
      this.touch(window, this.now());
      const close = () => this.queue(() => this.sweepAndEnd(window));
      return { id: window.id, startedAt: window.startedAt, close };
    });
  }

  /** A window with no write for its idleMs ends, so a close that never comes cannot hold every later write. */
  touch(window: Group, at: number): void {
    window.lastWriteAt = Math.max(window.lastWriteAt ?? at, at);
    this.endWhenIdle(window, window.idleMs);
  }

  endWhenIdle(window: Group, delay: number | undefined): void {
    clearTimeout(window.idleTimer);
    if (window.idleMs === undefined || !Number.isFinite(window.idleMs) || delay === undefined)
      return;
    window.idleTimer = setTimeout(
      () => {
        const left = window.idleMs! - (this.now() - (window.lastWriteAt ?? this.now()));
        if (left > 0) this.endWhenIdle(window, left);
        else this.background(() => this.sweepAndEnd(window));
      },
      Math.min(delay, MAX_TIMER_MS),
    );
    window.idleTimer.unref?.();
  }

  async sweepAndEnd(window: Group): Promise<HistoryEntry | null> {
    await this.sweep();
    return this.endWindow(window);
  }

  /** Commits an open window once; ending it again returns the entry it became. */
  async endWindow(window: Group): Promise<HistoryEntry | null> {
    if (!this.windows.includes(window)) return window.entry ?? null;
    clearTimeout(window.idleTimer);
    await this.commitClaim();
    this.windows = this.windows.filter((open) => open !== window);
    window.entry = (await this.commit(window)) ?? window.entry ?? null;
    return window.entry;
  }

  /** Every pending write, open window and outside group, committed: for flush and close. */
  async settleAll(): Promise<void> {
    await this.sweep();
    await this.commitClaim();
    for (const window of [...this.windows]) await this.endWindow(window);
    await this.commitOutside();
  }

  /** What took a removed path's place, dating its removal: an entry at the path, or a file at a folder above it. */
  standingAt(path: string): { at: string; stat: Stats } | undefined {
    const parts = path.split("/");
    for (let depth = 1; depth <= parts.length; depth += 1) {
      const at = parts.slice(0, depth).join("/");
      const stat = lstatSync(join(this.dir, at), { throwIfNoEntry: false });
      if (!stat) return undefined;
      if (at === path || !stat.isDirectory()) return { at, stat };
    }
    return undefined;
  }

  /** What a write of `path` would have to delete: a file or link at or above it, or a file in a folder at it. */
  inTheWay(path: string, deleted: ReadonlySet<string>): string | undefined {
    const standing = this.standingAt(path);
    if (!standing) return undefined;
    if (standing.stat.isSymbolicLink()) return standing.at;
    if (standing.at === path && !standing.stat.isDirectory()) return undefined;
    // On-disk names, so an entry `a` found at `A` on a case-insensitive disk matches its tracked paths.
    const real = realpathSync.native(join(this.dir, standing.at));
    const at = relative(realpathSync.native(this.dir), real).split(sep).join("/");
    if (standing.at !== path) return deleted.has(at) ? undefined : at;
    return fileLeftIn(real, at, deleted);
  }

  /** Writes `target` (path to hash, null deletes) as one entry of `who`'s. */
  async writeAs(
    who: HistoryWho,
    label: string,
    target: Map<string, string | null>,
    extra: Partial<HistoryEntry>,
  ): Promise<HistoryEntry | null> {
    this.assertWritable();
    const changes = [...target]
      .filter(([path, hash]) => (this.tracked.get(path)?.hash ?? null) !== hash)
      .sort(([, a], [, b]) => Number(a !== null) - Number(b !== null));
    const deleted = new Set(changes.filter(([, hash]) => hash === null).map(([path]) => path));
    const blocked = changes
      .filter(([, hash]) => hash !== null)
      .map(([path]) => this.inTheWay(path, deleted))
      .find(Boolean);
    if (blocked) throw new Error(`${blocked} is in the way; move or delete it, then try again.`);
    const group = this.newGroup(who, label);
    this.windows.push(group);
    try {
      for (const [path, hash] of changes) await this.writeProjectFile(path, hash);
      await this.sweep();
    } finally {
      this.windows = this.windows.filter((open) => open !== group);
    }
    return this.commit(group, extra);
  }

  /** Writes one project file (null deletes it), first leaving the running operation's receipt for its echo. */
  async writeProjectFile(path: string, hash: string | null): Promise<void> {
    this.assertWritable();
    const absPath = join(this.dir, path);
    const { writeToken } = this;
    if (writeToken) {
      const version = hash === null ? DELETED_VERSION : hashVersion(hash);
      recordFileWriteReceipt(absPath, { path, version, writeToken });
    }
    if (hash === null) {
      this.assertWritable();
      rmSync(absPath, { force: true });
    } else {
      await removeEmptyFolders(absPath);
      await this.blobs.writeTo(hash, absPath, () => this.assertWritable());
    }
  }

  entry(id: string): HistoryEntry {
    const entry = this.log.entries.find((candidate) => candidate.id === id);
    if (!entry) throw new Error("That change is no longer kept in this project's history.");
    return entry;
  }

  undoLabel(entry: HistoryEntry): string {
    if (!entry.undoes) return `Undid: ${entry.label}`;
    const original = this.log.entries.find((candidate) => candidate.id === entry.undoes);
    return `Redid: ${original?.label ?? entry.label}`;
  }

  async undoNow(id: string, who: HistoryWho, mode?: UndoMode): Promise<HistoryResult> {
    const entry = this.entry(id);
    const changed = this.movedOn(entry);
    if (changed.length && !mode) return { ok: false, conflict: this.conflict(entry, changed) };
    if (mode === "back-to-before") {
      const index = this.log.entries.indexOf(entry);
      const point = index > 0 ? this.log.entries[index - 1]!.id : START;
      return {
        ok: true,
        entry: await this.restoreNow(point, who, `Went back to before: ${entry.label}`),
      };
    }
    const target = new Map(
      entry.files
        .filter((file) => mode !== "keep-later-edits" || !changed.includes(file))
        .map((file) => [file.path, file.before]),
    );
    return {
      ok: true,
      entry: await this.writeAs(who, this.undoLabel(entry), target, {
        undoes: id,
        ...(entry.targets && { targets: entry.targets }),
      }),
    };
  }

  movedOn(entry: HistoryEntry): HistoryFileChange[] {
    return entry.files.filter((file) => (this.tracked.get(file.path)?.hash ?? null) !== file.after);
  }

  next(direction: "back" | "forward", who: HistoryWho): HistoryEntry | undefined {
    // An outside change has no known author, so it is everyone's; a step commits it after the held claim.
    const mine = (author: HistoryWho) => sameWho(author, who) || sameWho(author, OUTSIDE);
    const pending = [...[...this.windows].reverse(), this.outside, this.claimed?.group].find(
      (group) => group?.changes.size && mine(group.who),
    );
    if (pending) return direction === "back" ? this.pendingEntry(pending) : undefined;
    const everyone = this.options.undoScope === "everyone";
    const ofOpenTurn = (entry: HistoryEntry) =>
      this.windows.some((open) => open.parts?.has(entry.id));
    return stepTarget(
      this.log.entries,
      direction,
      (entry) => entry.files.length > 0 && (mine(entry.who) || (everyone && !ofOpenTurn(entry))),
    );
  }

  /** A pending group as the entry it becomes once committed (a window's part gets a fresh id). */
  pendingEntry(group: Group): HistoryEntry {
    const files = [...group.changes.values()].sort((a, b) => a.path.localeCompare(b.path));
    const { id, who, label, startedAt, lastWriteAt } = group;
    return {
      id,
      who,
      label,
      startedAt,
      endedAt: lastWriteAt ?? this.now(),
      files,
      ...(group.targets?.length && { targets: group.targets }),
    };
  }

  conflict(
    entry: HistoryEntry,
    changed: HistoryFileChange[],
  ): { files: string[]; newer: string[] } {
    const paths = new Set(changed.map((file) => file.path));
    const after = this.log.entries.slice(this.log.entries.indexOf(entry) + 1);
    const newer = after.filter((later) => later.files.some((file) => paths.has(file.path)));
    return { files: [...paths], newer: newer.map((later) => later.id) };
  }

  async restoreNow(point: string, who: HistoryWho, label: string): Promise<HistoryEntry | null> {
    const files = manifestAt(this.log, point);
    if (!files) throw new Error("That point is no longer kept in this project's history.");
    const target = new Map<string, string | null>(
      [...this.tracked.keys()].map((path) => [path, null]),
    );
    for (const [path, hash] of files) target.set(path, hash);
    return this.writeAs(who, label, target, { restoredTo: point });
  }

  /** Settles, then runs `task` with its writes labelled `writeToken`. */
  operation<T>(writeToken: string | undefined, task: () => Promise<T>): Promise<T> {
    return this.queue(async () => {
      await this.settle();
      this.writeToken = writeToken;
      try {
        return await task();
      } finally {
        this.writeToken = undefined;
      }
    });
  }

  pointLabel(point: string): string {
    return point === START ? "the start" : this.entry(point).label;
  }

  api(): ProjectHistory {
    return {
      projectId: this.projectId,
      beginWindow: (who, label, options = {}) =>
        this.beginWindow(
          who,
          label,
          options.idleMs ?? this.options.maxGroupMs ?? 30_000,
          options.exclusive === true,
        ),
      claim: async (who, label, paths, options = {}) => {
        await Promise.all(paths.map((path) => this.adopting.get(this.logPath(path))));
        return this.queue(() => this.claimNow(who, label, paths, options));
      },
      noteChange: (path) => {
        if (!this.closed) this.noteChange(path);
      },
      list: () => {
        this.assertOpen();
        return listOf(this.log);
      },
      step: (direction, who, { writeToken } = {}) =>
        this.operation(writeToken, async () => {
          const target = this.next(direction, who);
          return target ? this.undoNow(target.id, who) : { ok: true, entry: null };
        }),
      undo: (id, { who, mode, writeToken }) =>
        this.operation(writeToken, () => this.undoNow(id, who, mode)),
      restore: (point, who, { writeToken } = {}) =>
        this.operation(writeToken, () =>
          this.restoreNow(point, who, `Restored: ${this.pointLabel(point)}`),
        ),
      peek: (point) => {
        this.assertOpen();
        return peekOf(this.log, point);
      },
      checkout: (entryId, side, emptyDir) =>
        this.queue(async () => {
          this.entry(entryId);
          if (!existsSync(this.dir)) throw new Error(`The project folder is gone: ${this.dir}`);
          const dest = resolve(emptyDir);
          if (isWithin(this.dir, dest))
            throw new Error(`Checkout writes outside the project only: ${dest}`);
          if ((await readdir(dest).catch(missingIsEmpty)).length > 0)
            throw new Error(`Checkout writes into an empty folder only: ${dest}`);
          const files = manifestAround(this.log, entryId, side)!;
          try {
            for (const [path, hash] of files) await this.blobs.writeTo(hash, join(dest, path));
          } catch (error) {
            for (const name of await readdir(dest).catch(() => []))
              await rm(join(dest, name), { recursive: true, force: true });
            throw error;
          }
        }),
      next: (direction, who) => {
        this.assertOpen();
        return this.next(direction, who);
      },
      readBlob: async (hash) => {
        this.assertOpen();
        return this.blobs.read(hash);
      },
      pin: (id, pinned) => {
        this.assertOpen();
        this.entry(id);
        if (pinned) this.log.pins.add(id);
        else this.log.pins.delete(id);
        this.persistLog({ type: "pin", id, pinned });
      },
      onEntry: (listener) => {
        this.listeners.add(listener);
        return () => this.listeners.delete(listener);
      },
      checkpoint: () => this.queue(() => this.settle()),
      flush: () => this.queue(() => this.settleAll()),
      replacedAtPath: () => this.whereFolder() === "replaced",
      close: () =>
        (this.closing ??= (async () => {
          // A copy cut short would leave its media out of the baseline, so a change made while closed is lost.
          await Promise.all(this.adopting.values());
          if (this.notedTimer) clearTimeout(this.notedTimer);
          this.stopHearing?.();
          const settled = this.queue(() => this.settleAll());
          this.closed = true;
          await settled;
        })()),
    };
  }
}

/** Compares real on-disk paths; `.native` gives a case-insensitive disk's real letter case, so no alias gets in. */
function isWithin(dir: string, path: string): boolean {
  let probe = resolve(path);
  while (!existsSync(probe) && dirname(probe) !== probe) probe = dirname(probe);
  const rel = relative(realpathSync.native(dir), realpathSync.native(probe));
  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
}

function missingIsEmpty(error: NodeJS.ErrnoException): string[] {
  if (error.code === "ENOENT") return [];
  throw error;
}

/** A call on a history that was closed, or whose folder is now another project. */
export class HistoryClosedError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "HistoryClosedError";
  }
}

/** Opens a project's history: every write to its files becomes an entry that can be undone or restored. */
export async function openProjectHistory(options: ProjectHistoryOptions): Promise<ProjectHistory> {
  if (!existsSync(options.projectDir))
    throw new HistoryClosedError(`${options.projectDir} is gone or now another project.`);
  const projectId = projectHistoryId(options.projectDir, options.historyRoot);
  const release = await takeHistoryOwnership(
    join(options.historyRoot, projectId),
    options.ownerWaitMs ?? 5000,
    options.ownerUrl,
  );
  try {
    const blobs = await openBlobStore(join(options.historyRoot, projectId, "blobs"));
    const closedWindow = options.closedWindowAfterOwnership?.() ?? options.closedWindow;
    const engine = new Engine({ ...options, closedWindow }, projectId, blobs);
    await engine.queue(async () => {
      await engine.start();
      engine.hearWrites();
    });
    pruneGoneProjectHistoriesDaily(options.historyRoot, engine.now(), {
      onError: options.onError,
      budgetMs: options.pruneGoneProjectsBudgetMs,
    });
    const api = engine.api();
    return {
      ...api,
      close: () => api.close().finally(release),
    };
  } catch (error) {
    release();
    throw error;
  }
}

/** A project's history as its log stands now, read without the owner lock: it reads while another process owns it. */
export interface ProjectHistoryView {
  list(): HistoryListItem[];
  peek(point: string): Record<string, string> | null;
  readBlob(hash: string): Promise<Buffer>;
}

/** Reads only: takes no lock and files, prunes or writes nothing; an owner's half-appended last line is skipped. */
export function readProjectHistory(
  options: Pick<ProjectHistoryOptions, "projectDir" | "historyRoot">,
): ProjectHistoryView {
  const dir = resolve(options.projectDir);
  const id = readId(dir);
  const home =
    id && isRecordedFolder(join(options.historyRoot, id), statSync(dir))
      ? join(options.historyRoot, id)
      : null;
  const read = home && readLog(logFileIn(home), () => {});
  const log = withoutHiddenPaths(read || { baseline: new Map(), entries: [], pins: new Set() });
  return {
    list: () => listOf(log),
    peek: (point) => peekOf(log, point),
    readBlob: async (hash) => {
      if (!home) throw new Error("That is not a history blob.");
      return readBlob(join(home, "blobs"), hash);
    },
  };
}