@valbuild/server 0.103.0 → 0.103.1

package/dist/valbuild-server.esm.js

@@ -8,12 +8,13 @@ import path__default from 'path';
 import fs, { promises } from 'fs';
 import vm from 'node:vm';
 import { Module, createRequire } from 'node:module';
-import { resolveSchemaSourceFixForError, getErrorMessageFromUnknownJson, Patch, ParentRef, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api } from '@valbuild/shared/internal';
+import { resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api } from '@valbuild/shared/internal';
 import { createUIRequestHandler } from '@valbuild/ui/server';
 import crypto$1 from 'crypto';
 import z$1, { z } from 'zod';
 import sizeOf from 'image-size';
 import { fromError } from 'zod-validation-error';
+import os from 'os';
 import { transform } from 'sucrase';
 import http from 'http';
 import https from 'https';
@@ -3268,49 +3269,1030 @@ class JsonEntryFilesFingerprint {
 }
 
 /**
- * Computes the changed patch parent references based on the current patches and the patch IDs to be deleted.
+ * The order of the pending patches, held in one flat, append-only text file.
  *
- * NOTE: patches that will be deleted are not included in the changed patches, since they will be deleted any how.
+ * ## Why a log and not links between the patches
  *
- * @param currentPatches - The array of current patches.
- * @param deletePatchIds - The array of patch IDs to be deleted.
- * @returns An object containing the changed patches with their corresponding parent references.
+ * The store this replaces kept the order in the patches themselves: every record
+ * carried a `parentRef`, and the directory a record lived in was named after that
+ * parent. Reading the chain meant walking those links from `head`, and the walk
+ * stopped dead — silently — at the first id nothing on disk answered for.
+ *
+ * That is not a hypothetical. A store with 410 patches lost exactly one record,
+ * and the 51 patches written after it became unreachable: `/stat` counted the
+ * directories and announced 410, `GET /patches` walked the links and delivered
+ * 359, and the studio waited forever for 51 ids that no longer had a path back to
+ * `head`. One missing file cost every edit made after it.
+ *
+ * So the order lives in one place and the patches reference nothing. A patch
+ * directory is self-contained data; this file says what order the directories go
+ * in. Removing a line cannot orphan the lines below it, because there is nothing
+ * below it to orphan — the entry after a dropped one is simply next.
+ *
+ * ## Why text
+ *
+ * It is read by people during exactly the incidents that make it interesting, and
+ * `cat` should be enough. One entry per line, whitespace-separated, id first:
+ *
+ * ```
+ * val-patch-log v1
+ * 659b8cfa-065c-47d1-8d82-fc69a2ac72a9 2026-08-27T11:46:13.730Z /content/authors.val.ts
+ * ```
+ *
+ * Position in the file IS the order. There is deliberately no sequence number:
+ * a number stored beside the thing it describes is a number that can disagree
+ * with it, and then something has to decide which one lies.
+ *
+ * The timestamp and path are there to make the file readable, not to be believed
+ * — `patch.json` owns those fields. Nothing here is a second copy of state that
+ * anything reads back.
  */
-function computeChangedPatchParentRefs(currentPatches, deletePatchIds) {
-  let lastNonDeletedPatchIndex = -1;
-  const changedPatches = {};
-  for (let i = 0; i < currentPatches.length; i++) {
-    const current = currentPatches[i];
-    if (
-    // skip all patches that will be deleted:
-    deletePatchIds.includes(current.patchId)) {
-      var _currentPatches;
-      if (
-      // skip change if the patch after is deleted anyway:
-      !deletePatchIds.includes((_currentPatches = currentPatches[i + 1]) === null || _currentPatches === void 0 ? void 0 : _currentPatches.patchId)) {
-        if (
-        // set next patch to point to head if it exists:
-        lastNonDeletedPatchIndex === -1 && currentPatches[i + 1]) {
-          changedPatches[currentPatches[i + 1].patchId] = {
-            type: "head",
-            headBaseSha: current.baseSha
-          };
-        } else if (
-        // set next patch to point to the last non-deleted patch:
-        currentPatches[lastNonDeletedPatchIndex] && currentPatches[i + 1]) {
-          changedPatches[currentPatches[i + 1].patchId] = {
-            type: "patch",
-            patchId: currentPatches[lastNonDeletedPatchIndex].patchId
-          };
+
+const PATCH_LOG_FILE_NAME = "patches.log";
+const HEADER = "val-patch-log v1";
+
+/**
+ * Something that is wrong with the file but does not stop it being read.
+ *
+ * Reported rather than thrown, because a log that is 99% intact is worth reading
+ * and then repairing. Only a file that cannot be understood at all is fatal, and
+ * that is a `status` on the read result, not a problem in this list.
+ */
+
+function isModuleFilePath(path) {
+  return path.startsWith("/") && path.includes(".val.");
+}
+function isPatchId(patchId) {
+  return patchId.length > 0 && !/\s/.test(patchId);
+}
+function formatPatchLogLine(entry) {
+  return `${entry.patchId} ${entry.createdAt} ${entry.path}`;
+}
+
+/**
+ * Split on the first two runs of whitespace only: a module file path may contain
+ * spaces, and it is last precisely so that it can.
+ */
+function parsePatchLogLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const match = /^(\S+)\s+(\S+)\s+(.+)$/.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const [, patchId, createdAt, path] = match;
+  if (!isPatchId(patchId) || !isModuleFilePath(path)) {
+    return null;
+  }
+  return {
+    patchId,
+    createdAt,
+    path
+  };
+}
+function serializePatchLog(entries) {
+  return [HEADER, ...entries.map(formatPatchLogLine), ""].join("\n");
+}
+function readPatchLog(logFilePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(logFilePath, "utf-8");
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT") {
+      return {
+        status: "absent"
+      };
+    }
+    return {
+      status: "unreadable",
+      message: `Could not read ${logFilePath}: ${err instanceof Error ? err.message : "unknown error"}`
+    };
+  }
+  return parsePatchLog(raw);
+}
+function parsePatchLog(raw) {
+  const problems = [];
+  // A zero-byte file is a store that was created and then interrupted before the
+  // header landed. Empty, not broken: there are no patches either way.
+  if (raw === "") {
+    return {
+      status: "ok",
+      entries: [],
+      problems
+    };
+  }
+  const endsWithNewline = raw.endsWith("\n");
+  const lines = raw.split("\n");
+  // `split` always leaves a trailing "" when the text ends in a newline; when it
+  // does not, the last element is a line whose write never finished.
+  const tornFinalLine = endsWithNewline ? null : lines[lines.length - 1];
+  lines.pop();
+  if (tornFinalLine !== null && tornFinalLine.trim() !== "") {
+    problems.push({
+      type: "torn-final-line",
+      line: tornFinalLine
+    });
+  }
+
+  // Only consume the first line when it really is the header. A headerless file
+  // is reported, but its first line is still offered to the entry parser rather
+  // than eaten: dropping a real patch to pay for a missing header would be the
+  // same silent data loss this store exists to stop.
+  const firstLine = (lines[0] ?? "").replace(/\r$/, "");
+  let firstEntryIndex = 0;
+  if (firstLine === HEADER) {
+    firstEntryIndex = 1;
+  } else if (firstLine.startsWith("val-patch-log ")) {
+    problems.push({
+      type: "unsupported-version",
+      header: firstLine
+    });
+    firstEntryIndex = 1;
+  } else {
+    problems.push({
+      type: "missing-header",
+      firstLine
+    });
+  }
+  const entries = [];
+  const seen = new Set();
+  lines.slice(firstEntryIndex).forEach((rawLine, index) => {
+    const line = rawLine.replace(/\r$/, "");
+    // 1-based and counted from the top of the file, so they match what an editor
+    // shows the person reading this report.
+    const lineNumber = firstEntryIndex + index + 1;
+    if (line.trim() === "") {
+      return;
+    }
+    const entry = parsePatchLogLine(line);
+    if (entry === null) {
+      problems.push({
+        type: "unparseable-line",
+        lineNumber,
+        line
+      });
+      return;
+    }
+    if (seen.has(entry.patchId)) {
+      problems.push({
+        type: "duplicate-entry",
+        patchId: entry.patchId,
+        lineNumber
+      });
+      return;
+    }
+    seen.add(entry.patchId);
+    entries.push(entry);
+  });
+  return {
+    status: "ok",
+    entries,
+    problems
+  };
+}
+
+/**
+ * fsync the directory holding a file, so a rename or create survives a power cut.
+ *
+ * Best-effort: opening a directory is not permitted on Windows, and a store that
+ * refuses to work there to buy durability nobody asked for is the worse trade.
+ */
+function fsyncDir(dirPath) {
+  let fd;
+  try {
+    fd = fs.openSync(dirPath, "r");
+    fs.fsyncSync(fd);
+  } catch {
+    // ignore: see above
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * Add one entry to the end of the log.
+ *
+ * A single `writeSync` on an append-only descriptor, then fsync: the whole line
+ * reaches the file or none of it does, and a reader that catches it mid-flight
+ * discards the partial last line rather than misreading it.
+ *
+ * Callers must hold the patch lock. That is what makes "the torn line can only be
+ * the last one" true, and it is why this does not try to be safe against
+ * concurrent appends on its own.
+ */
+function appendPatchLogEntry(logFilePath, entry) {
+  const dirPath = path__default.dirname(logFilePath);
+  fs.mkdirSync(dirPath, {
+    recursive: true
+  });
+  if (!fs.existsSync(logFilePath)) {
+    writePatchLogFile(logFilePath, []);
+  }
+  const fd = fs.openSync(logFilePath, "a");
+  try {
+    fs.writeSync(fd, `${formatPatchLogLine(entry)}\n`);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Replace the log wholesale — used by delete and by repair.
+ *
+ * Write a sibling temp file, fsync it, then rename over the original: a rename is
+ * atomic, so a reader either sees the old log or the new one and never a
+ * half-rewritten file. In-place truncation would have a window where the log is
+ * short and the store looks like it lost patches.
+ *
+ * Callers must hold the patch lock.
+ */
+function writePatchLogFile(logFilePath, entries) {
+  const dirPath = path__default.dirname(logFilePath);
+  fs.mkdirSync(dirPath, {
+    recursive: true
+  });
+  const tmpPath = `${logFilePath}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmpPath, "w");
+  try {
+    fs.writeSync(fd, serializePatchLog(entries));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmpPath, logFilePath);
+  fsyncDir(dirPath);
+}
+
+/**
+ * The on-disk shape of the local-dev patch store.
+ *
+ * ```
+ * .val/patches/
+ *   patches.log            the order, and the only place it lives
+ *   patches.repair.log     what repair has done, for the person who has to know
+ *   <patchId>/patch.json   one plain, self-contained directory per patch
+ *   <patchId>/base.json    written when the patch is published
+ *   <patchId>/files/…      binary payloads for this patch's file ops
+ * ```
+ *
+ * A directory is named after the patch it holds, and a record references nothing
+ * outside itself. That is the whole design, and it is a direct answer to how the
+ * old layout failed: there, a directory was named after a record's PARENT, so
+ * reading the store meant following links, and one absent record silently cut off
+ * every patch written after it.
+ *
+ * The invariant this module exists to hold up is narrow and worth stating: **the
+ * announced set and the delivered set are the same array.** `getStat` and
+ * `fetchPatches` both come out of one `readPatchStore` call, so they cannot report
+ * different numbers - which is exactly what they did when this broke, announcing
+ * 410 patches and delivering 359 with no error in between.
+ */
+
+const PATCH_REPAIR_LOG_FILE_NAME = "patches.repair.log";
+const FSPatch = z.object({
+  path: z.string().refine(p => p.startsWith("/") && p.includes(".val."), "Path is not valid. Must start with '/' and include '.val.'"),
+  patch: Patch,
+  patchId: z.string(),
+  baseSha: z.string().refine(p => true),
+  authorId: z.string().refine(p => true).nullable(),
+  createdAt: z.string().datetime(),
+  coreVersion: z.string().nullable(),
+  sessionId: z.string().nullable()
+});
+const FSPatchBase = z.object({
+  baseSha: z.string().refine(p => true),
+  timestamp: z.string().datetime()
+});
+
+/**
+ * Something wrong with the store that a reader can see.
+ *
+ * Every one of these used to be invisible. Reporting them is the point: the
+ * failure that motivated this rewrite was not that the store broke, it was that
+ * breaking looked exactly like working.
+ */
+
+function patchesLogFile(patchesDir) {
+  return path__default.join(patchesDir, PATCH_LOG_FILE_NAME);
+}
+function patchRepairLogFile(patchesDir) {
+  return path__default.join(patchesDir, PATCH_REPAIR_LOG_FILE_NAME);
+}
+function patchDir(patchesDir, patchId) {
+  return path__default.join(patchesDir, patchId);
+}
+function patchRecordFile(patchesDir, patchId) {
+  return path__default.join(patchDir(patchesDir, patchId), "patch.json");
+}
+function patchBaseFile(patchesDir, patchId) {
+  return path__default.join(patchDir(patchesDir, patchId), "base.json");
+}
+function patchBinaryFile(patchesDir, patchId, filePath) {
+  return path__default.join(patchDir(patchesDir, patchId), "files", filePath, path__default.basename(filePath));
+}
+function patchBinaryFileMetadata(patchesDir, patchId, filePath) {
+  return path__default.join(patchDir(patchesDir, patchId), "files", filePath, "metadata.json");
+}
+
+/** Names that live in the patches directory but are not patches. */
+const RESERVED_NAMES = new Set([PATCH_LOG_FILE_NAME, PATCH_REPAIR_LOG_FILE_NAME]);
+function readJsonFile(filePath, parser) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    return {
+      error: err instanceof Error ? err.message : "unknown error"
+    };
+  }
+  if (raw === "") {
+    return {
+      error: "the file is empty"
+    };
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return {
+      error: `it is not valid JSON: ${err instanceof Error ? err.message : "unknown error"}`
+    };
+  }
+  const parsed = parser.safeParse(json);
+  if (!parsed.success) {
+    return {
+      error: fromError(parsed.error).toString()
+    };
+  }
+  return {
+    data: parsed.data
+  };
+}
+function listPatchDirNames(patchesDir) {
+  return fs.readdirSync(patchesDir, {
+    withFileTypes: true
+  }).filter(dirent => dirent.isDirectory() && !RESERVED_NAMES.has(dirent.name)).map(dirent => dirent.name);
+}
+
+/**
+ * Read the whole store: the order, the records, and everything wrong with it.
+ *
+ * One call, one answer. Callers that need only the ids and callers that need the
+ * ops both use this, which is what stops them disagreeing.
+ */
+function readPatchStore(patchesDir) {
+  if (!fs.existsSync(patchesDir)) {
+    return {
+      status: "ok",
+      entries: [],
+      problems: []
+    };
+  }
+  let dirNames;
+  try {
+    dirNames = listPatchDirNames(patchesDir);
+  } catch (err) {
+    return {
+      status: "unreadable",
+      message: `Could not list ${patchesDir}: ${err instanceof Error ? err.message : "unknown error"}`
+    };
+  }
+  const problems = [];
+  const logRes = readPatchLog(patchesLogFile(patchesDir));
+  if (logRes.status === "unreadable") {
+    return {
+      status: "unreadable",
+      message: logRes.message
+    };
+  }
+  let logEntries;
+  if (logRes.status === "absent") {
+    if (dirNames.length === 0) {
+      return {
+        status: "ok",
+        entries: [],
+        problems: []
+      };
+    }
+    logEntries = reconstructLogEntries(patchesDir, dirNames);
+    if (logEntries.length > 0) {
+      problems.push({
+        type: "reconstructed-log",
+        entryCount: logEntries.length
+      });
+    }
+  } else {
+    logEntries = logRes.entries;
+    for (const problem of logRes.problems) {
+      problems.push({
+        type: "log",
+        problem
+      });
+    }
+  }
+  const entries = [];
+  const named = new Set();
+  for (const logEntry of logEntries) {
+    named.add(logEntry.patchId);
+    const read = readPatchRecord(patchesDir, logEntry.patchId);
+    if (read.error !== undefined) {
+      problems.push({
+        type: "unreadable-patch",
+        name: logEntry.patchId,
+        dir: patchDir(patchesDir, logEntry.patchId),
+        message: read.error
+      });
+      continue;
+    }
+    const baseFile = patchBaseFile(patchesDir, logEntry.patchId);
+    const baseRes = fs.existsSync(baseFile) ? readJsonFile(baseFile, FSPatchBase) : undefined;
+    entries.push({
+      patchId: logEntry.patchId,
+      record: read.data,
+      base: (baseRes === null || baseRes === void 0 ? void 0 : baseRes.data) ?? null
+    });
+  }
+  for (const name of dirNames) {
+    if (named.has(name)) {
+      continue;
+    }
+    // Told apart by whether the directory holds a usable record. One is a patch
+    // whose contents are lost and has to be reported; the other is a crash
+    // leftover nothing ever read.
+    const read = readPatchRecord(patchesDir, name);
+    if (read.error !== undefined) {
+      problems.push({
+        type: "unreadable-patch",
+        name,
+        dir: path__default.join(patchesDir, name),
+        message: read.error
+      });
+    } else {
+      problems.push({
+        type: "orphan-directory",
+        name,
+        dir: path__default.join(patchesDir, name)
+      });
+    }
+  }
+  return {
+    status: "ok",
+    entries,
+    problems
+  };
+}
+
+/**
+ * Read one patch directory, insisting it holds the patch it is named after.
+ *
+ * The name check is not a formality. A directory named after something other
+ * than the record inside is how the previous layout worked - the name was the
+ * record's PARENT - so this is what tells a store this version can use from one
+ * it cannot.
+ */
+function readPatchRecord(patchesDir, name) {
+  const file = patchRecordFile(patchesDir, name);
+  if (!fs.existsSync(file)) {
+    return {
+      error: `there is no ${file}`
+    };
+  }
+  const res = readJsonFile(file, FSPatch);
+  if (res.error !== undefined) {
+    return {
+      error: res.error
+    };
+  }
+  if (res.data.patchId !== name) {
+    return {
+      error: `it holds ${res.data.patchId}, not the patch its directory is named after`
+    };
+  }
+  return {
+    data: res.data
+  };
+}
+
+/**
+ * Rebuild the order from the records when the log itself is gone.
+ *
+ * `createdAt` is the only ordering left, and it is not a perfect one, so the
+ * caller reports that the order was guessed rather than presenting it as fact.
+ */
+function reconstructLogEntries(patchesDir, dirNames) {
+  const entries = [];
+  for (const name of dirNames) {
+    const res = readJsonFile(path__default.join(patchesDir, name, "patch.json"), FSPatch);
+    if (res.error !== undefined || res.data.patchId !== name) {
+      continue;
+    }
+    entries.push({
+      patchId: res.data.patchId,
+      createdAt: res.data.createdAt,
+      path: res.data.path
+    });
+  }
+  entries.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  return entries;
+}
+
+/** Write a patch record so that a reader sees all of it or none of it. */
+function writePatchRecord(patchesDir, patchId, record) {
+  const dir = patchDir(patchesDir, patchId);
+  fs.mkdirSync(dir, {
+    recursive: true
+  });
+  const file = patchRecordFile(patchesDir, patchId);
+  const tmpFile = `${file}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmpFile, "w");
+  try {
+    fs.writeSync(fd, JSON.stringify(record));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmpFile, file);
+}
+
+/**
+ * Add a patch to the store.
+ *
+ * Record first, then the log line, and the order is the safety property: an
+ * interrupted append leaves a directory nothing points at, which repair sweeps
+ * up. The reverse order would leave the log naming a patch that is not there -
+ * the exact state this whole rewrite exists to make unreachable.
+ *
+ * Callers must hold the patch lock.
+ */
+function appendPatch(patchesDir, record) {
+  const patchId = record.patchId;
+  writePatchRecord(patchesDir, patchId, record);
+  const entry = {
+    patchId,
+    createdAt: record.createdAt,
+    path: record.path
+  };
+  appendPatchLogEntry(patchesLogFile(patchesDir), entry);
+  return entry;
+}
+/**
+ * Bring the store back to a state where the log and the directories agree.
+ *
+ * Safe in a way the old layout's repair could never be: the log is a flat list,
+ * so dropping an entry does not orphan the entries after it. There is nothing to
+ * re-link, which is why this can run unattended where re-parenting a chain could
+ * not.
+ *
+ * A patch that cannot be read is removed rather than kept around to fail again
+ * on every load. That does discard unpublished work, which is why
+ * {@link RepairAction} carries the reason, why it is written to
+ * `patches.repair.log`, and why the caller is expected to tell the person
+ * editing.
+ *
+ * Callers must hold the patch lock.
+ */
+function repairPatchStore(patchesDir, read) {
+  const actions = [];
+  const needsRewrite = read.problems.some(problem => problem.type === "unreadable-patch" || problem.type === "reconstructed-log" || problem.type === "log");
+  for (const problem of read.problems) {
+    if (problem.type === "unreadable-patch") {
+      remove(problem.dir);
+      actions.push({
+        type: "removed-unreadable-patch",
+        name: problem.name,
+        because: problem.message
+      });
+    } else if (problem.type === "orphan-directory") {
+      remove(problem.dir);
+      actions.push({
+        type: "removed-orphan-directory",
+        name: problem.name
+      });
+    }
+  }
+  if (needsRewrite) {
+    writePatchLogFile(patchesLogFile(patchesDir), read.entries.map(entry => ({
+      patchId: entry.patchId,
+      createdAt: entry.record.createdAt,
+      path: entry.record.path
+    })));
+    actions.push({
+      type: "rewrote-log",
+      entryCount: read.entries.length
+    });
+  }
+  if (actions.length > 0) {
+    recordRepair(patchesDir, actions);
+  }
+  return actions;
+}
+function remove(dir) {
+  try {
+    fs.rmSync(dir, {
+      recursive: true,
+      force: true
+    });
+  } catch {
+    // Left in place. It is inert either way - nothing reads a directory the log
+    // does not name, and the log has already been rewritten without it.
+  }
+}
+
+/**
+ * Leave a trail. Repair drops a person's unpublished edits, and doing that
+ * without saying so anywhere durable is how you get someone certain they saved
+ * something and no way to tell them what happened to it.
+ */
+function recordRepair(patchesDir, actions) {
+  const at = new Date().toISOString();
+  const lines = actions.map(action => {
+    if (action.type === "removed-unreadable-patch") {
+      return `${at} removed ${action.name}: ${action.because}`;
+    }
+    if (action.type === "removed-orphan-directory") {
+      return `${at} removed orphan directory ${action.name}`;
+    }
+    return `${at} rewrote the log with ${action.entryCount} entries`;
+  });
+  try {
+    fs.appendFileSync(patchRepairLogFile(patchesDir), `${lines.join("\n")}\n`, "utf-8");
+  } catch {
+    // An audit trail that cannot be written is not a reason to fail the repair.
+  }
+}
+
+/**
+ * Last resort: move the whole store aside and start empty.
+ *
+ * A rename, never a delete. What is being given up on here is someone's
+ * unpublished work, and the least this can do is say where it went.
+ *
+ * Callers must hold the patch lock.
+ */
+function resetPatchStore(patchesDir, reason) {
+  if (!fs.existsSync(patchesDir)) {
+    return {
+      movedTo: patchesDir
+    };
+  }
+  const movedTo = `${patchesDir}-corrupt-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  try {
+    fs.renameSync(patchesDir, movedTo);
+  } catch (err) {
+    return {
+      error: `Could not move ${patchesDir} aside: ${err instanceof Error ? err.message : "unknown error"}`
+    };
+  }
+  try {
+    fs.mkdirSync(patchesDir, {
+      recursive: true
+    });
+    fs.appendFileSync(patchRepairLogFile(patchesDir), `${new Date().toISOString()} reset the store (${reason}); the previous contents are in ${movedTo}\n`, "utf-8");
+  } catch {
+    // The rename is the part that mattered.
+  }
+  return {
+    movedTo
+  };
+}
+
+/** One line per problem, for a log line or an API error a person has to act on. */
+function describePatchStoreProblems(problems) {
+  return problems.map(problem => {
+    switch (problem.type) {
+      case "unreadable-patch":
+        return `The change ${problem.name} could not be read: ${problem.message} (${problem.dir})`;
+      case "orphan-directory":
+        return `${problem.dir} is not listed in the log and is not being used.`;
+      case "reconstructed-log":
+        return `The log was missing, so the order of ${problem.entryCount} change(s) was reconstructed from their timestamps and may not be exact.`;
+      case "log":
+        return describeLogProblem(problem.problem);
+    }
+  });
+}
+function describeLogProblem(problem) {
+  switch (problem.type) {
+    case "missing-header":
+      return `The log does not start with its header (it starts with ${JSON.stringify(problem.firstLine)}).`;
+    case "unsupported-version":
+      return `The log says ${JSON.stringify(problem.header)}, which this version of Val does not understand.`;
+    case "unparseable-line":
+      return `Line ${problem.lineNumber} of the log could not be read: ${JSON.stringify(problem.line)}`;
+    case "duplicate-entry":
+      return `The change ${problem.patchId} is listed twice in the log (line ${problem.lineNumber}).`;
+    case "torn-final-line":
+      return `The last line of the log was not finished being written and was ignored.`;
+  }
+}
+
+/**
+ * A timed, cross-process lock over the patches directory.
+ *
+ * ## Why there is one at all
+ *
+ * Nothing serialized writes to the patch store before this. Two dev-server route
+ * handlers, two browser tabs and the CLI all wrote to the same directory, and the
+ * one guard that existed — a `mkdir` whose stated purpose was to throw when the
+ * directory already existed — had its `EEXIST` swallowed by a bare `catch {}`, so
+ * a colliding write silently overwrote the patch that was already there. A store
+ * that loses a patch that way loses every patch chained behind it too.
+ *
+ * ## Why a file, and why timed
+ *
+ * A real lock manager is more than this problem needs: the contenders are a
+ * handful of processes on one machine, holding it for milliseconds. What that
+ * does need is to survive a holder that dies — `kill -9` on a dev server, a
+ * laptop lid, a crashed test — without leaving the store permanently unwritable.
+ * Hence an expiry: a lock nobody renews stops being a lock.
+ *
+ * The file is plain `key: value` text on purpose. When something is stuck, the
+ * question is always "who is holding it and since when", and `cat .val/patches.lock`
+ * should answer it without a tool.
+ *
+ * ## The takeover race
+ *
+ * Two processes can decide the same lock is stale at the same moment, and a blind
+ * `unlink` would then let the second one delete the FIRST one's fresh lock. So a
+ * stale lock is only removed after being read twice, unchanged, across a poll
+ * interval, and the `owner` nonce is what "unchanged" means. Whoever wins the
+ * `wx` create afterwards is unique regardless, because that create is atomic —
+ * the double read is what stops a winner being deleted a moment after winning.
+ */
+
+const PATCH_LOCK_FILE_NAME = "patches.lock";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_POLL_MS = 25;
+
+/**
+ * Locks this process is currently holding, released on exit.
+ *
+ * A best-effort courtesy: it turns the common crash — an unhandled throw, a
+ * ctrl-C — into an immediately reusable store instead of one that waits out a
+ * TTL. The TTL is still what makes correctness not depend on this running.
+ */
+const heldLocks = new Set();
+let exitHookInstalled = false;
+function installExitHook() {
+  if (exitHookInstalled) {
+    return;
+  }
+  exitHookInstalled = true;
+  process.once("exit", () => {
+    heldLocks.forEach(lock => {
+      try {
+        lock.release();
+      } catch {
+        // Nothing useful can be done during exit.
+      }
+    });
+  });
+}
+function formatPatchLockInfo(info) {
+  return [`owner: ${info.owner}`, `pid: ${info.pid}`, `host: ${info.host}`, `op: ${info.op}`, `acquired: ${info.acquiredAt}`, `expires: ${info.expiresAt}`, ""].join("\n");
+}
+function parsePatchLockInfo(raw) {
+  const fields = {};
+  for (const line of raw.split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    fields[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+  }
+  const {
+    owner,
+    pid,
+    host,
+    op,
+    acquired,
+    expires
+  } = fields;
+  if (!owner || !acquired || !expires) {
+    return null;
+  }
+  const parsedPid = Number.parseInt(pid ?? "", 10);
+  return {
+    owner,
+    pid: Number.isNaN(parsedPid) ? -1 : parsedPid,
+    host: host ?? "",
+    op: op ?? "",
+    acquiredAt: acquired,
+    expiresAt: expires
+  };
+}
+function readRaw(lockFilePath) {
+  try {
+    return fs.readFileSync(lockFilePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function isExpired(info, nowMs) {
+  // An unparseable lock file is treated as expired. It is either a half-written
+  // acquisition or something that is not a lock at all, and neither should be
+  // able to wedge the store forever.
+  if (info === null) {
+    return true;
+  }
+  const expiresAt = Date.parse(info.expiresAt);
+  if (Number.isNaN(expiresAt)) {
+    return true;
+  }
+  return expiresAt <= nowMs;
+}
+function describeHolder(info) {
+  if (info === null) {
+    return "the lock file could not be read";
+  }
+  return `held by pid ${info.pid} on ${info.host || "unknown host"} for "${info.op}" since ${info.acquiredAt} (expires ${info.expiresAt})`;
+}
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Try to create the lock file exclusively.
+ *
+ * `wx` is `O_CREAT | O_EXCL`: the create either happens or reports EEXIST, with
+ * no window in between. Everything else in this module exists to handle the
+ * EEXIST case; this is the part that actually provides mutual exclusion.
+ */
+function tryCreate(lockFilePath, info) {
+  let fd;
+  try {
+    fd = fs.openSync(lockFilePath, "wx");
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST") {
+      return "exists";
+    }
+    return {
+      error: err instanceof Error ? err.message : "unknown error"
+    };
+  }
+  try {
+    fs.writeSync(fd, formatPatchLockInfo(info));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return "created";
+}
+async function acquirePatchLock(lockFilePath, options) {
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const deadline = now() + timeoutMs;
+  try {
+    fs.mkdirSync(path__default.dirname(lockFilePath), {
+      recursive: true
+    });
+  } catch (err) {
+    return {
+      status: "error",
+      message: `Could not create the directory for ${lockFilePath}: ${err instanceof Error ? err.message : "unknown error"}`
+    };
+  }
+  let lastSeenHolder = null;
+  for (;;) {
+    const acquiredAt = now();
+    const info = {
+      owner: crypto$1.randomUUID(),
+      pid: process.pid,
+      host: os.hostname(),
+      op: options.op,
+      acquiredAt: new Date(acquiredAt).toISOString(),
+      expiresAt: new Date(acquiredAt + options.ttlMs).toISOString()
+    };
+    const created = tryCreate(lockFilePath, info);
+    if (created === "created") {
+      const lock = createLock(lockFilePath, info, options.ttlMs, now);
+      installExitHook();
+      heldLocks.add(lock);
+      return {
+        status: "acquired",
+        lock
+      };
+    }
+    if (created !== "exists") {
+      return {
+        status: "error",
+        message: `Could not create ${lockFilePath}: ${created.error}`
+      };
+    }
+    const rawBefore = readRaw(lockFilePath);
+    if (rawBefore === null) {
+      // Released between the failed create and the read. Go straight round again.
+      continue;
+    }
+    lastSeenHolder = parsePatchLockInfo(rawBefore);
+    if (isExpired(lastSeenHolder, now())) {
+      // Read twice across a poll interval before removing it: an unchanged stale
+      // file is one nobody is renewing, and requiring the second read is what
+      // stops two processes both deciding to clear it and the loser wiping the
+      // winner's brand-new lock.
+      await sleep(pollMs);
+      const rawAfter = readRaw(lockFilePath);
+      if (rawAfter === rawBefore && isExpired(lastSeenHolder, now())) {
+        try {
+          fs.unlinkSync(lockFilePath);
+        } catch {
+          // Someone else got there first, which is the outcome we wanted anyway.
         }
       }
-    } else {
-      lastNonDeletedPatchIndex = i;
+      continue;
+    }
+    if (now() >= deadline) {
+      return {
+        status: "busy",
+        holder: lastSeenHolder,
+        message: `Timed out after ${timeoutMs}ms waiting for the Val patch lock at ${lockFilePath}: ${describeHolder(lastSeenHolder)}`
+      };
     }
+    await sleep(pollMs);
   }
-  return {
-    changedPatches
+}
+function createLock(lockFilePath, initialInfo, defaultTtlMs, now) {
+  let info = initialInfo;
+  let released = false;
+  const stillOurs = () => {
+    var _parsePatchLockInfo;
+    const raw = readRaw(lockFilePath);
+    if (raw === null) {
+      return false;
+    }
+    return ((_parsePatchLockInfo = parsePatchLockInfo(raw)) === null || _parsePatchLockInfo === void 0 ? void 0 : _parsePatchLockInfo.owner) === info.owner;
+  };
+  const lock = {
+    get info() {
+      return info;
+    },
+    renew(ttlMs) {
+      if (released || !stillOurs()) {
+        return false;
+      }
+      const next = {
+        ...info,
+        expiresAt: new Date(now() + (ttlMs ?? defaultTtlMs)).toISOString()
+      };
+      const fd = fs.openSync(lockFilePath, "w");
+      try {
+        fs.writeSync(fd, formatPatchLockInfo(next));
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+      info = next;
+      return true;
+    },
+    release() {
+      if (released) {
+        return;
+      }
+      released = true;
+      heldLocks.delete(lock);
+      // Only ours. If the lock expired and someone else took it, the file now
+      // belongs to them and deleting it would hand the store to a third party.
+      if (stillOurs()) {
+        try {
+          fs.unlinkSync(lockFilePath);
+        } catch {
+          // Already gone.
+        }
+      }
+    }
   };
+  return lock;
+}
+
+/**
+ * Run `fn` while holding the lock, and always give it back.
+ *
+ * The only shape callers should use: a `release()` that a throw can skip is how
+ * a store ends up locked by a process that has long since moved on.
+ */
+async function withPatchLock(lockFilePath, options, fn) {
+  const acquired = await acquirePatchLock(lockFilePath, options);
+  if (acquired.status !== "acquired") {
+    return acquired;
+  }
+  try {
+    return {
+      status: "ok",
+      value: await fn(acquired.lock)
+    };
+  } finally {
+    acquired.lock.release();
+  }
 }
 
 async function uploadRemoteFile(contentHost, project, bucket, fileHash, fileExt, fileBuffer, auth) {
@@ -3381,6 +4363,20 @@ class ValOpsFS extends ValOps {
    * content lives behind a thunk that `JSON.stringify` drops).
    */
 
+  /**
+   * Unpublished changes repair threw away, waiting to be told to somebody.
+   *
+   * Held here and drained by the next `getStat`, because stat is the channel
+   * that always flows. The case worth reporting is a repair that removed
+   * EVERYTHING - which is what an old store looks like - and then there is
+   * nothing left for the studio to fetch, so a notice riding on `fetchPatches`
+   * would never be collected. Drained rather than kept, because this has to be
+   * said once: a permanent flag would put a toast on the screen forever.
+   *
+   * Held in memory only: a restart loses it, and that is the right trade. The
+   * durable record is `patches.repair.log`.
+   */
+  removedPatchNotices = [];
   async onInit() {
     // do nothing
   }
@@ -3474,14 +4470,28 @@ class ValOpsFS extends ValOps {
       const serializedSchemas = Object.fromEntries(Object.entries(schemas).map(([path, schema]) => [path, serializeSchemaSafely(schema)]));
       const currentJsonEntriesSha = this.jsonEntryFilesFingerprint.compute(serializedSchemas);
       const jsonEntryFilePaths = this.jsonEntryFilesFingerprint.entryFilePaths(serializedSchemas);
-      const patchData = await this.readPatches();
-      const patches = [];
-      // TODO: use proper patch sequences when available:
-      for (const [patchId] of Object.entries(patchData.patches).sort(([, a], [, b]) => {
-        return a.createdAt.localeCompare(b.createdAt, undefined);
-      })) {
-        patches.push(patchId);
+
+      // The SAME read `fetchPatches` delivers from. Announcing out of one source
+      // and delivering out of another is what let this store tell a studio about
+      // 410 unpublished changes and then hand over 359 of them, with nothing in
+      // between reporting that anything was wrong.
+      const announceRes = await this.readStore();
+      if (announceRes.status === "error") {
+        return {
+          type: "error",
+          error: {
+            message: announceRes.message
+          }
+        };
       }
+      const patches = announceRes.entries.map(entry => entry.patchId);
+      // Drained here, on the channel that always flows. A repair that removed
+      // everything leaves the studio nothing to fetch, so a notice riding on
+      // `GET /patches` would sit here unread.
+      const removed = this.removedPatchNotices.splice(0, this.removedPatchNotices.length);
+      const removedNotice = removed.length > 0 ? {
+        removed
+      } : {};
       // something changed: return immediately
       const didChange = !params ||
       // An entry file changed on disk: nothing else here can see that, since a
@@ -3496,6 +4506,7 @@ class ValOpsFS extends ValOps {
           schemaSha: currentSchemaSha,
           sourcesSha: currentSourcesSha,
           patches,
+          ...removedNotice,
           jsonEntriesSha: currentJsonEntriesSha
         };
       }
@@ -3620,6 +4631,7 @@ class ValOpsFS extends ValOps {
         schemaSha: currentSchemaSha,
         sourcesSha: currentSourcesSha,
         patches,
+        ...removedNotice,
         jsonEntriesSha: currentJsonEntriesSha
       };
     } catch (err) {
@@ -3639,134 +4651,152 @@ class ValOpsFS extends ValOps {
       };
     }
   }
-  async readPatches(includes) {
-    const patchesCacheDir = this.getPatchesDir();
-    let patchJsonFiles = [];
-    if (!this.host.directoryExists || this.host.directoryExists && this.host.directoryExists(patchesCacheDir)) {
-      patchJsonFiles = this.host.readDirectory(patchesCacheDir, ["patch.json"], [], []);
-    }
-    const patches = {};
-    const errors = [];
-    const parsedUnsortedFsPatches = patchJsonFiles.map(file => path__default.basename(path__default.dirname(file))).map(patchDir => [patchDir, this.parseJsonFile(this.getPatchFilePath(patchDir), FSPatch), this.host.fileExists(this.getPatchBaseFile(patchDir)) ? this.parseJsonFile(this.getPatchBaseFile(patchDir), FSPatchBase) : undefined]);
-    parsedUnsortedFsPatches.forEach(([dir, parsedPatch, parsedBase]) => {
-      if (parsedPatch.error) {
-        errors.push({
-          ...parsedPatch.error,
-          parentPatchId: dir
-        });
-      } else if (parsedBase && parsedBase.error) {
-        errors.push({
-          ...parsedBase.error,
-          parentPatchId: dir
-        });
-      } else {
-        const patchId = parsedPatch.data.patchId;
-        if (includes && includes.length > 0 && !includes.includes(patchId)) {
-          return;
-        }
-        patches[patchId] = {
-          path: parsedPatch.data.path,
-          patch: parsedPatch.data.patch,
-          parentRef: parsedPatch.data.parentRef,
-          baseSha: parsedPatch.data.baseSha,
-          createdAt: parsedPatch.data.createdAt,
-          authorId: parsedPatch.data.authorId,
-          appliedAt: null
-        };
-      }
-    });
 
-    // If there are patches, but no head. error
-    if (Object.keys(errors).length > 0) {
+  /**
+   * The one read every other read comes out of.
+   *
+   * `getStat` announces from this and `fetchPatches` delivers from this, so the
+   * two cannot disagree. They used to: `getStat` counted the directories on disk
+   * while `fetchPatches` walked the parent links between them, and when a single
+   * record went missing the first said 410 and the second said 359 — with no
+   * error anywhere, because a walk that runs out of links just stops.
+   *
+   * Anything wrong is reported, then repaired, and reset only if repair does not
+   * settle it. In that order, and never silently.
+   */
+  async readStore() {
+    const read = readPatchStore(this.getPatchesDir());
+    if (read.status === "unreadable") {
       return {
-        patches,
-        errors
+        status: "error",
+        message: read.message
       };
     }
-    return {
-      patches
-    };
-  }
-  getParentPatchIdFromParentRef(parentRef) {
-    return parentRef.type === "head" ? "head" : parentRef.patchId;
+    if (read.problems.length === 0) {
+      return {
+        status: "ok",
+        entries: read.entries
+      };
+    }
+    return this.repairStore(read);
   }
-  async fetchPatches(filters) {
-    const fetchPatchesRes = await this.fetchPatchesFromFS(!!filters.excludePatchOps);
-    const sortedPatches = this.createPatchChain(fetchPatchesRes.patches).map(patchData => {
-      if (filters.excludePatchOps) {
+
+  /**
+   * Report, repair, and reset only if repair did not take.
+   *
+   * Reached only when something is actually wrong, so the healthy path — which
+   * is every stat poll — never touches the lock.
+   */
+  async repairStore(read) {
+    const patchesDir = this.getPatchesDir();
+    for (const problem of describePatchStoreProblems(read.problems)) {
+      console.warn("Val: something is wrong with the patch store.", problem);
+    }
+    const locked = await withPatchLock(this.getPatchLockFile(), {
+      ttlMs: 30_000,
+      op: "repair the patch store"
+    }, () => {
+      // Read again under the lock. What was seen above was seen without it, so
+      // a write may have landed since — and repairing against a stale picture
+      // is how the old delete path destroyed live patches.
+      const current = readPatchStore(patchesDir);
+      if (current.status !== "ok") {
         return {
-          ...patchData,
-          patch: undefined
+          status: "error",
+          message: current.message
         };
       }
-      return patchData;
-    }).filter(patchData => {
-      if (filters.patchIds && filters.patchIds.length > 0) {
-        return filters.patchIds.includes(patchData.patchId);
+      if (current.problems.length === 0) {
+        return {
+          status: "ok",
+          entries: current.entries
+        };
       }
-      return true;
+      for (const action of repairPatchStore(patchesDir, current)) {
+        if (action.type === "removed-unreadable-patch") {
+          console.warn(`Val: removed the unpublished change ${action.name} because ${action.because}. See ${patchesDir}/${PATCH_REPAIR_LOG_FILE_NAME}.`);
+          // Queued rather than only logged: this is someone's unpublished
+          // work being thrown away, and a server console is not somewhere the
+          // person editing is looking.
+          this.removedPatchNotices.push({
+            patchId: action.name,
+            reason: action.because
+          });
+        } else if (action.type === "removed-orphan-directory") {
+          // Not queued. Nothing ever read this - it is a record whose log line
+          // never landed - so there is no edit to tell anyone about.
+          console.warn(`Val: removed the unused patch directory ${action.name}.`);
+        }
+      }
+      const after = readPatchStore(patchesDir);
+      if (after.status === "ok" && after.problems.length === 0) {
+        return {
+          status: "ok",
+          entries: after.entries
+        };
+      }
+      // Repair did not settle it, so the store is not something anyone can
+      // describe any more. Move it aside — a rename, never a delete — and say
+      // where it went.
+      const reset = resetPatchStore(patchesDir, "it could not be repaired automatically");
+      if ("error" in reset) {
+        return {
+          status: "error",
+          message: reset.error
+        };
+      }
+      console.warn(`Val: the patch store could not be repaired, so it was reset. The previous contents are in ${reset.movedTo}.`);
+      return {
+        status: "ok",
+        entries: []
+      };
     });
-    return {
-      patches: sortedPatches,
-      errors: fetchPatchesRes.errors
-    };
-  }
-  async fetchPatchesFromFS(excludePatchOps) {
-    const patches = {};
-    const {
-      errors,
-      patches: allPatches
-    } = await this.readPatches();
-    for (const [patchIdS, patch] of Object.entries(allPatches)) {
-      const patchId = patchIdS;
-      patches[patchId] = {
-        patch: excludePatchOps ? undefined : patch.patch,
-        parentRef: patch.parentRef,
-        path: patch.path,
-        baseSha: patch.baseSha,
-        createdAt: patch.createdAt,
-        authorId: patch.authorId,
-        appliedAt: patch.appliedAt
+    if (locked.status !== "ok") {
+      // Someone else holds the lock, quite possibly to run this same repair.
+      // Serving what was read is safe — those entries are the ones that ARE
+      // readable — and the next read tries again.
+      console.warn(`Val: could not repair the patch store now. ${locked.message}`);
+      return {
+        status: "ok",
+        entries: read.entries
       };
     }
-    if (errors && errors.length > 0) {
+    return locked.value;
+  }
+  async fetchPatches(filters) {
+    const storeRes = await this.readStore();
+    if (storeRes.status === "error") {
+      // Surfaced, not returned as an empty list. An empty answer to "what is
+      // pending" is indistinguishable from "nothing is pending", and the studio
+      // would render published content over unpublished edits without a word.
+      const none = [];
       return {
-        patches,
-        errors
+        patches: none,
+        error: {
+          message: storeRes.message
+        }
+        // The cast is unavoidable: the return type is conditional on a generic
+        // that TypeScript cannot narrow from a value.
       };
     }
+    const requested = filters.patchIds && filters.patchIds.length > 0 ? new Set(filters.patchIds) : null;
+    const patches = storeRes.entries.filter(entry => requested === null || requested.has(entry.patchId)).map(entry => ({
+      patchId: entry.patchId,
+      path: entry.record.path,
+      patch: filters.excludePatchOps ? undefined : entry.record.patch,
+      createdAt: entry.record.createdAt,
+      authorId: entry.record.authorId,
+      baseSha: entry.record.baseSha,
+      // Publishing deletes the whole store, so in fs mode a patch that is
+      // still here has not been applied. `base.json` is read for its parse
+      // errors, not for this.
+      appliedAt: null
+    }));
     return {
       patches
     };
   }
 
-  // #region createPatchChain
-  createPatchChain(unsortedPatchRecord) {
-    var _Object$entries$find;
-    // TODO: Error handling
-    const nextPatch = {};
-    Object.keys(unsortedPatchRecord).forEach(patchId => {
-      const patch = unsortedPatchRecord[patchId];
-      if (patch.parentRef.type === "head") {
-        nextPatch["head"] = patchId;
-      } else {
-        nextPatch[patch.parentRef.patchId] = patchId;
-      }
-    });
-    const sortedPatches = [];
-    let nextPatchId = (_Object$entries$find = Object.entries(unsortedPatchRecord).find(([, patch]) => patch.parentRef.type === "head")) === null || _Object$entries$find === void 0 ? void 0 : _Object$entries$find[0];
-    while (!!nextPatchId && nextPatchId in unsortedPatchRecord) {
-      const patch = unsortedPatchRecord[nextPatchId];
-      delete patch["parentRef"];
-      sortedPatches.push({
-        ...patch,
-        patchId: nextPatchId
-      });
-      nextPatchId = nextPatch[nextPatchId];
-    }
-    return sortedPatches;
-  }
-
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   parseJsonFile(filePath, parser) {
     if (!this.host.fileExists(filePath)) {
@@ -3841,53 +4871,60 @@ class ValOpsFS extends ValOps {
       };
     }
   }
-  async saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId) {
-    const patchDir = this.getParentPatchIdFromParentRef(parentRef);
-    try {
-      const baseSha = await this.getBaseSha();
-      const data = {
-        patch,
-        patchId,
-        parentRef,
-        path,
-        authorId,
-        sessionId,
-        baseSha,
-        coreVersion: Internal.VERSION.core,
-        createdAt: new Date().toISOString()
-      };
-      const headParentPatchId = "head";
-      if (patchDir !== headParentPatchId && !this.host.fileExists(this.getPatchFilePath(headParentPatchId))) {
-        console.error("Val: out-of-band patch detected.", this.getPatchFilePath(headParentPatchId));
-        return result.err({
-          errorType: "patch-head-conflict"
-        });
-      }
-      const writeRes = this.host.tryWriteUf8File(this.getPatchFilePath(patchDir), JSON.stringify(data));
-      if (writeRes.type === "error") {
+  async saveSourceFilePatch(path, patch, patchId, _parentRef, authorId, sessionId) {
+    const patchesDir = this.getPatchesDir();
+    const record = {
+      patch,
+      patchId,
+      path,
+      authorId,
+      sessionId,
+      baseSha: await this.getBaseSha(),
+      coreVersion: Internal.VERSION.core,
+      createdAt: new Date().toISOString()
+    };
+    /*
+     * `parentRef` is ignored here, and that is the point of the log.
+     *
+     * It used to be the directory name, which is how a client working from a
+     * stale view could write a patch whose parent had never landed and strand
+     * every patch behind it. With the order held in one append-only list the
+     * server decides where a patch goes: it goes last. There is no parent to
+     * name, nothing to point at, and so nothing that can point at nothing.
+     *
+     * The parameter stays because `ValOpsHttp` genuinely needs it — the content
+     * api runs its own chain and is told the parent — but in fs mode a stale
+     * parent is not an error to refuse, it is a fact with no consequences.
+     *
+     * What that gives up is early detection of a patch computed against a
+     * different state: two tabs editing the same array can produce an op that no
+     * longer fits. That is caught where it actually shows — applying the patch —
+     * and handled by dropping it and saying so, rather than by refusing writes
+     * up front and making every interleaved edit a round trip.
+     */
+    const locked = await withPatchLock(this.getPatchLockFile(), {
+      ttlMs: 10_000,
+      op: "PUT /patches"
+    }, () => {
+      try {
+        appendPatch(patchesDir, record);
+      } catch (err) {
         return result.err({
           errorType: "other",
-          error: writeRes.error,
-          message: "Failed to write patch file"
+          message: `Failed to write the patch: ${err instanceof Error ? err.message : "unknown error"}`
         });
       }
       return result.ok({
         patchId
       });
-    } catch (err) {
-      if (err instanceof Error) {
-        return result.err({
-          errorType: "other",
-          error: err,
-          message: err.message
-        });
-      }
+    });
+    if (locked.status !== "ok") {
       return result.err({
         errorType: "other",
-        error: err,
-        message: "Unknown error"
+        message: locked.message
       });
     }
+    return locked.value;
   }
   async getSourceFile(path) {
     const filePath = path__default.join(this.rootDir, path);
@@ -3924,10 +4961,14 @@ class ValOpsFS extends ValOps {
       };
     }
   }
-  async saveBase64EncodedBinaryFileFromPatch(filePath, parentRef, patchId, data, _type, metadata) {
-    const patchDir = this.getParentPatchIdFromParentRef(parentRef);
-    const patchFilePath = this.getBinaryFilePath(filePath, patchDir);
-    const metadataFilePath = this.getBinaryFileMetadataPath(filePath, patchDir);
+  async saveBase64EncodedBinaryFileFromPatch(filePath, _parentRef, patchId, data, _type, metadata) {
+    // Keyed by the patch's own id, so the parent is not needed and is not asked
+    // for. Uploads arrive before the patch record does, which is fine: the
+    // directory sits there unreferenced until the log line that names it lands,
+    // and repair sweeps it up if that never happens.
+    const patchesDir = this.getPatchesDir();
+    const patchFilePath = patchBinaryFile(patchesDir, patchId, filePath);
+    const metadataFilePath = patchBinaryFileMetadata(patchesDir, patchId, filePath);
     try {
       if (data === null) {
         this.host.deleteFile(patchFilePath);
@@ -3967,15 +5008,7 @@ class ValOpsFS extends ValOps {
     }
   }
   async getBase64EncodedBinaryFileMetadataFromPatch(filePath, type, patchId) {
-    const patchDirRes = await this.getParentPatchIdFromPatchId(patchId);
-    if (result.isErr(patchDirRes)) {
-      return {
-        errors: [{
-          message: "Failed to get patch dir from patch id"
-        }]
-      };
-    }
-    const metadataFilePath = this.getBinaryFileMetadataPath(filePath, patchDirRes.value);
+    const metadataFilePath = patchBinaryFileMetadata(this.getPatchesDir(), patchId, filePath);
     if (!this.host.fileExists(metadataFilePath)) {
       return {
         errors: [{
@@ -4011,95 +5044,132 @@ class ValOpsFS extends ValOps {
     };
   }
   async getBase64EncodedBinaryFileFromPatch(filePath, patchId) {
-    const patchDirRes = await this.getParentPatchIdFromPatchId(patchId);
-    if (!result.isOk(patchDirRes)) {
-      return null;
-    }
-    const absPath = this.getBinaryFilePath(filePath, patchDirRes.value);
+    // Straight from the id. This used to read and parse every patch on disk to
+    // work out which directory the file was under, on every single image request.
+    const absPath = patchBinaryFile(this.getPatchesDir(), patchId, filePath);
     if (!this.host.fileExists(absPath)) {
       return null;
     }
     return this.host.readBinaryFile(absPath);
   }
   async deletePatches(patchIds) {
-    const deleted = [];
-    const patchDirMapRes = await this.getParentPatchIdFromPatchIdMap();
-    if (result.isErr(patchDirMapRes)) {
+    const patchesDir = this.getPatchesDir();
+    const requested = new Set(patchIds);
+    const locked = await withPatchLock(this.getPatchLockFile(), {
+      ttlMs: 30_000,
+      op: "DELETE /patches"
+    }, () => {
+      const read = readPatchStore(patchesDir);
+      if (read.status !== "ok") {
+        return {
+          status: "error",
+          message: read.message
+        };
+      }
+      /*
+       * Deleting is now dropping lines from a list.
+       *
+       * It used to be a three-step re-link per surviving patch — rewrite a
+       * record, remove the destination directory, rename another one over it —
+       * with the plan computed from a snapshot taken before hundreds of file
+       * reads, every failure swallowed by a `console.error`, and one step that
+       * unconditionally removed whatever occupied the destination. An
+       * interruption anywhere in it stranded every patch after the hole.
+       */
+      writePatchLogFile(patchesLogFile(patchesDir), read.entries.filter(entry => !requested.has(entry.patchId)).map(entry => ({
+        patchId: entry.patchId,
+        createdAt: entry.record.createdAt,
+        path: entry.record.path
+      })));
+      // The log first, then the directories. A crash in between leaves
+      // directories nothing names, which is inert and swept up on the next
+      // read; the other order would leave the log naming patches that are gone.
+      const deleted = [];
+      const errors = {};
+      for (const patchId of patchIds) {
+        try {
+          fs.rmSync(patchDir(patchesDir, patchId), {
+            recursive: true,
+            force: true
+          });
+          deleted.push(patchId);
+        } catch (err) {
+          // Reported. This endpoint used to answer "deleted" unconditionally —
+          // `deleted` and `errors` were never written to at all — so a delete
+          // that failed looked exactly like one that worked.
+          errors[patchId] = {
+            message: `Could not remove the files for ${patchId}: ${err instanceof Error ? err.message : "unknown error"}`
+          };
+        }
+      }
+      return {
+        status: "ok",
+        deleted,
+        errors
+      };
+    });
+    if (locked.status !== "ok") {
+      return {
+        error: {
+          message: locked.message
+        }
+      };
+    }
+    if (locked.value.status === "error") {
       return {
         error: {
-          message: "Failed to get patch dir map"
+          message: locked.value.message
         }
       };
     }
-    const currentPatches = this.createPatchChain((await this.fetchPatchesFromFS(false)).patches);
-    this.updateOrderedPatches(computeChangedPatchParentRefs(currentPatches, patchIds), patchDirMapRes.value, patchIds);
+    const {
+      deleted,
+      errors
+    } = locked.value;
+    if (Object.keys(errors).length > 0) {
+      return {
+        deleted,
+        errors
+      };
+    }
     return {
       deleted
     };
   }
   async deleteAllPatches() {
-    const patchesCacheDir = this.getPatchesDir();
-    const tmpDir = path__default.join(this.rootDir, ValOpsFS.VAL_DIR, "patches-deleted-" + crypto.randomUUID());
-    try {
-      this.host.moveDir(patchesCacheDir, tmpDir);
-      this.host.deleteDir(tmpDir);
-      return {};
-    } catch (err) {
-      if (err instanceof Error) {
+    const patchesDir = this.getPatchesDir();
+    const locked = await withPatchLock(this.getPatchLockFile(), {
+      ttlMs: 30_000,
+      op: "delete all patches"
+    }, () => {
+      if (!fs.existsSync(patchesDir)) {
+        return {};
+      }
+      const tmpDir = path__default.join(this.rootDir, ValOpsFS.VAL_DIR, "patches-deleted-" + crypto.randomUUID());
+      try {
+        // One rename takes the log and the directories together, so the store
+        // is empty and self-consistent from the first instant rather than
+        // part-way through. It is also the cleanup route for a store this
+        // version refuses to read: discarding everything always works.
+        this.host.moveDir(patchesDir, tmpDir);
+        this.host.deleteDir(tmpDir);
+        return {};
+      } catch (err) {
         return {
           error: {
-            message: `Got an error while deleting patches: ${err.message}`
+            message: `Got an error while deleting patches: ${err instanceof Error ? err.message : "unknown error"}`
           }
         };
       }
+    });
+    if (locked.status !== "ok") {
       return {
         error: {
-          message: "Got an unexpected error while deleting patches"
+          message: locked.message
         }
       };
     }
-  }
-  updateOrderedPatches(updates, patchDirMap, deletePatchIds) {
-    for (const patchId of deletePatchIds) {
-      const patchDir = patchDirMap[patchId];
-      if (!patchDir) {
-        console.error("Could not find patch dir for patch id scheduled for deletion: ", patchId);
-        continue;
-      }
-      try {
-        this.host.deleteDir(this.getFullPatchDir(patchDir));
-      } catch (err) {
-        console.error("Failed to delete patch dir", err);
-      }
-    }
-    for (const [patchIdS, parentRef] of Object.entries(updates.changedPatches)) {
-      const prevParentPatchId = patchDirMap[patchIdS];
-      if (!prevParentPatchId) {
-        console.error("Could not find previous parent patch id for deleted patch id: ", patchIdS);
-        continue;
-      }
-      const newParentPatchId = parentRef.type === "head" ? "head" : parentRef.patchId;
-      const currentPatchDataRes = this.parseJsonFile(this.getPatchFilePath(prevParentPatchId), FSPatch);
-      if (currentPatchDataRes.error) {
-        console.error("Failed to parse patch file while fixing patch chain after deleted patch", {
-          updates
-        }, currentPatchDataRes.error);
-        continue;
-      }
-      const newPatchData = currentPatchDataRes.data;
-      newPatchData.parentRef = parentRef;
-      try {
-        this.host.writeUf8File(this.getPatchFilePath(prevParentPatchId), JSON.stringify(newPatchData));
-        if (this.host.directoryExists(this.getFullPatchDir(newParentPatchId))) {
-          this.host.deleteDir(this.getFullPatchDir(newParentPatchId));
-        }
-        this.host.moveDir(this.getFullPatchDir(prevParentPatchId), this.getFullPatchDir(newParentPatchId));
-      } catch (err) {
-        console.error("Failed fix patch chain after deleted patch", {
-          updates
-        }, err);
-      }
-    }
+    return locked.value;
   }
   async saveOrUploadFiles(preparedCommit, mode, auth) {
     const updatedFiles = [];
@@ -4162,30 +5232,13 @@ class ValOpsFS extends ValOps {
         uploadedRemoteRefs.push(ref);
       }
     }
-    const patchIdToPatchDirMapRes = await this.getParentPatchIdFromPatchIdMap();
-    if (result.isErr(patchIdToPatchDirMapRes)) {
-      return {
-        updatedFiles,
-        uploadedRemoteRefs,
-        errors
-      };
-    }
-    const patchIdToPatchDirMap = patchIdToPatchDirMapRes.value;
     for (const [ref, {
       patchId
     }] of localFileDescriptors) {
       const filePath = ref;
       const absPath = path__default.join(this.rootDir, ...filePath.split("/"));
       try {
-        const patchDir = patchIdToPatchDirMap[patchId];
-        if (!patchDir) {
-          errors[absPath] = {
-            message: "Failed to find PatchDir for PatchId " + patchId,
-            filePath: filePath
-          };
-          continue;
-        }
-        this.host.copyFile(this.getBinaryFilePath(filePath, patchDir), absPath);
+        this.host.copyFile(patchBinaryFile(this.getPatchesDir(), patchId, filePath), absPath);
         updatedFiles.push(absPath);
       } catch (err) {
         errors[absPath] = {
@@ -4215,14 +5268,7 @@ class ValOpsFS extends ValOps {
         baseSha: await this.getBaseSha(),
         timestamp: new Date().toISOString()
       };
-      const patchDir = patchIdToPatchDirMap[patchId];
-      if (!patchDir) {
-        errors[`patchId:${patchId}`] = {
-          message: "Failed to find PatchDir for PatchId " + patchId
-        };
-        continue;
-      }
-      const absPath = this.getPatchBaseFile(patchDir);
+      const absPath = patchBaseFile(this.getPatchesDir(), patchId);
       try {
         this.host.writeUf8File(absPath, JSON.stringify(appliedAt));
       } catch (err) {
@@ -4267,47 +5313,18 @@ class ValOpsFS extends ValOps {
     }
     return createMetadataFromBuffer(type, mimeType, buffer);
   }
-  async getParentPatchIdFromPatchId(patchId) {
-    // This is not great. If needed we should find a better way
-    const patches = await this.readPatches();
-    if (patches.errors || patches.error) {
-      console.error("Failed to read patches", JSON.stringify(patches));
-      return result.err("failed-to-read-patches");
-    }
-    const patch = patches.patches[patchId];
-    if (!patch) {
-      console.error("Could not find patch with patchId: ", patchId);
-      return result.err("patch-not-found");
-    }
-    return result.ok(this.getParentPatchIdFromParentRef(patch.parentRef));
-  }
-  async getParentPatchIdFromPatchIdMap() {
-    const patches = await this.readPatches();
-    if (patches.errors || patches.error) {
-      console.error("Failed to read patches", JSON.stringify(patches));
-      return result.err("failed-to-read-patches");
-    }
-    return result.ok(Object.fromEntries(Object.entries(patches.patches).map(([patchId, value]) => [patchId, this.getParentPatchIdFromParentRef(value.parentRef)])));
-  }
 
   // #region fs file path helpers
   getPatchesDir() {
     return path__default.join(this.rootDir, ValOpsFS.VAL_DIR, "patches");
   }
-  getFullPatchDir(patchDir) {
-    return path__default.join(this.getPatchesDir(), patchDir);
-  }
-  getBinaryFilePath(filePath, patchDir) {
-    return path__default.join(this.getFullPatchDir(patchDir), "files", filePath, path__default.basename(filePath));
-  }
-  getBinaryFileMetadataPath(filePath, patchDir) {
-    return path__default.join(this.getFullPatchDir(patchDir), "files", filePath, "metadata.json");
-  }
-  getPatchFilePath(patchDir) {
-    return path__default.join(this.getFullPatchDir(patchDir), "patch.json");
-  }
-  getPatchBaseFile(patchDir) {
-    return path__default.join(this.getFullPatchDir(patchDir), "base.json");
+
+  /**
+   * Deliberately outside the patches directory: delete-all and reset rename that
+   * whole directory, and a lock that moves away with it is not holding anything.
+   */
+  getPatchLockFile() {
+    return path__default.join(this.rootDir, ValOpsFS.VAL_DIR, PATCH_LOCK_FILE_NAME);
   }
 }
 class FSOpsHost {
@@ -4390,22 +5407,6 @@ class FSOpsHost {
     fs.copyFileSync(from, to);
   }
 }
-const FSPatch = z.object({
-  path: z.string().refine(p => p.startsWith("/") && p.includes(".val."), "Path is not valid. Must start with '/' and include '.val.'"),
-  patch: Patch,
-  patchId: z.string(),
-  baseSha: z.string(),
-  parentRef: ParentRef,
-  authorId: z.string().refine(p => true).nullable(),
-  createdAt: z.string().datetime(),
-  coreVersion: z.string().nullable(),
-  // TODO: use this to check if patch is compatible with current core version?
-  sessionId: z.string().nullable()
-});
-const FSPatchBase = z.object({
-  baseSha: z.string().refine(p => true),
-  timestamp: z.string().datetime()
-});
 
 const textEncoder$2 = new TextEncoder();
 const PatchId = z.string().refine(s => !!s); // TODO: validate
@@ -6431,7 +7432,7 @@ const ValServer = (valModules, options, callbacks) => {
                 status: 409,
                 json: {
                   type: "patch-head-conflict",
-                  message: "Patch id conflict"
+                  message: "The change was written against a different starting point than the server has."
                 }
               };
             } else {
@@ -10759,4 +11760,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValServer, currentFixHandlers, decodeJwt, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };
+export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValServer, currentFixHandlers, decodeJwt, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };