@valbuild/server 0.102.0 → 0.103.1

package/dist/valbuild-server.cjs.prod.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var ts = require('typescript');
 var fp = require('@valbuild/core/fp');
-var core = require('@valbuild/core');
 var patch = require('@valbuild/core/patch');
+var core = require('@valbuild/core');
 var path = require('path');
 var fs = require('fs');
 var vm = require('node:vm');
@@ -16,6 +16,7 @@ var crypto$1 = require('crypto');
 var z = require('zod');
 var sizeOf = require('image-size');
 var zodValidationError = require('zod-validation-error');
+var os = require('os');
 var sucrase = require('sucrase');
 var http = require('http');
 var https = require('https');
@@ -48,6 +49,7 @@ var vm__default = /*#__PURE__*/_interopDefault(vm);
 var crypto__default = /*#__PURE__*/_interopDefault(crypto$1);
 var z__default = /*#__PURE__*/_interopDefault(z);
 var sizeOf__default = /*#__PURE__*/_interopDefault(sizeOf);
+var os__default = /*#__PURE__*/_interopDefault(os);
 var http__default = /*#__PURE__*/_interopDefault(http);
 var https__default = /*#__PURE__*/_interopDefault(https);
 var fs__default$1 = /*#__PURE__*/_interopDefault(fs$1);
@@ -102,7 +104,7 @@ function validateObjectProperties(nodes) {
  * validating its children.
  */
 function shallowValidateExpression(value) {
-  return ts__default["default"].isStringLiteralLike(value) || ts__default["default"].isNumericLiteral(value) || value.kind === ts__default["default"].SyntaxKind.TrueKeyword || value.kind === ts__default["default"].SyntaxKind.FalseKeyword || value.kind === ts__default["default"].SyntaxKind.NullKeyword || ts__default["default"].isArrayLiteralExpression(value) || ts__default["default"].isObjectLiteralExpression(value) || isValFileMethodCall(value) || isValImageMethodCall(value) || isValRemoteMethodCall(value) ? undefined : new ValSyntaxError("Expression must be a literal or call c.file / c.image / c.remote", value);
+  return ts__default["default"].isStringLiteralLike(value) || ts__default["default"].isNumericLiteral(value) || value.kind === ts__default["default"].SyntaxKind.TrueKeyword || value.kind === ts__default["default"].SyntaxKind.FalseKeyword || value.kind === ts__default["default"].SyntaxKind.NullKeyword || ts__default["default"].isArrayLiteralExpression(value) || ts__default["default"].isObjectLiteralExpression(value) ? undefined : new ValSyntaxError("Expression must be a literal", value);
 }
 
 /**
@@ -128,55 +130,8 @@ function evaluateExpression(value) {
     return fp.result.all(value.elements.map(evaluateExpression));
   } else if (ts__default["default"].isObjectLiteralExpression(value)) {
     return fp.pipe(validateObjectProperties(value.properties), fp.result.flatMap(assignments => fp.pipe(assignments.map(assignment => fp.pipe(evaluateExpression(assignment.initializer), fp.result.map(value => [assignment.name.text, value]))), fp.result.all)), fp.result.map(Object.fromEntries));
-  } else if (isValFileMethodCall(value)) {
-    return fp.pipe(findValFileNodeArg(value), fp.result.flatMap(ref => {
-      if (value.arguments.length === 2) {
-        return fp.pipe(evaluateExpression(value.arguments[1]), fp.result.map(metadata => ({
-          [core.FILE_REF_PROP]: ref.text,
-          _type: "file",
-          metadata
-        })));
-      } else {
-        return fp.result.ok({
-          [core.FILE_REF_PROP]: ref.text,
-          _type: "file"
-        });
-      }
-    }));
-  } else if (isValImageMethodCall(value)) {
-    return fp.pipe(findValImageNodeArg(value), fp.result.flatMap(ref => {
-      if (value.arguments.length === 2) {
-        return fp.pipe(evaluateExpression(value.arguments[1]), fp.result.map(metadata => ({
-          [core.FILE_REF_PROP]: ref.text,
-          _type: "file",
-          [core.FILE_REF_SUBTYPE_TAG]: "image",
-          metadata
-        })));
-      } else {
-        return fp.result.ok({
-          [core.FILE_REF_PROP]: ref.text,
-          _type: "file",
-          [core.FILE_REF_SUBTYPE_TAG]: "image"
-        });
-      }
-    }));
-  } else if (isValRemoteMethodCall(value)) {
-    return fp.pipe(findValRemoteNodeArg(value), fp.result.flatMap(ref => {
-      if (value.arguments.length === 2) {
-        return fp.pipe(evaluateExpression(value.arguments[1]), fp.result.map(metadata => ({
-          [core.FILE_REF_PROP]: ref.text,
-          _type: "remote",
-          metadata
-        })));
-      } else {
-        return fp.result.ok({
-          [core.FILE_REF_PROP]: ref.text,
-          _type: "remote"
-        });
-      }
-    }));
   } else {
-    return fp.result.err(new ValSyntaxError("Expression must be a literal or call c.file / c.image / c.remote", value));
+    return fp.result.err(new ValSyntaxError("Expression must be a literal", value));
   }
 }
 function findObjectPropertyAssignment(value, key) {
@@ -190,93 +145,6 @@ function findObjectPropertyAssignment(value, key) {
     return fp.result.ok(assignment);
   }));
 }
-function isValFileMethodCall(node) {
-  return ts__default["default"].isCallExpression(node) && ts__default["default"].isPropertyAccessExpression(node.expression) && ts__default["default"].isIdentifier(node.expression.expression) && node.expression.expression.text === "c" && node.expression.name.text === "file";
-}
-function isValImageMethodCall(node) {
-  return ts__default["default"].isCallExpression(node) && ts__default["default"].isPropertyAccessExpression(node.expression) && ts__default["default"].isIdentifier(node.expression.expression) && node.expression.expression.text === "c" && node.expression.name.text === "image";
-}
-function isValRemoteMethodCall(node) {
-  return ts__default["default"].isCallExpression(node) && ts__default["default"].isPropertyAccessExpression(node.expression) && ts__default["default"].isIdentifier(node.expression.expression) && node.expression.expression.text === "c" && node.expression.name.text === "remote";
-}
-function findValFileNodeArg(node) {
-  if (node.arguments.length === 0) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.file() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.file() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (!ts__default["default"].isStringLiteral(node.arguments[0])) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.file() call: ref must be a string literal`, node));
-  }
-  const refNode = node.arguments[0];
-  return fp.result.ok(refNode);
-}
-function findValRemoteNodeArg(node) {
-  if (node.arguments.length === 0) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.remote() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.remote() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (!ts__default["default"].isStringLiteral(node.arguments[0])) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.remote() call: ref must be a string literal`, node));
-  }
-  const refNode = node.arguments[0];
-  return fp.result.ok(refNode);
-}
-function findValImageNodeArg(node) {
-  if (node.arguments.length === 0) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.image() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.image() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (!ts__default["default"].isStringLiteral(node.arguments[0])) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.image() call: ref must be a string literal`, node));
-  }
-  const refNode = node.arguments[0];
-  return fp.result.ok(refNode);
-}
-function findValFileMetadataArg(node) {
-  if (node.arguments.length === 0) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.file() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.file() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (node.arguments.length === 2) {
-    if (!ts__default["default"].isObjectLiteralExpression(node.arguments[1])) {
-      return fp.result.err(new ValSyntaxError(`Invalid c.file() call: metadata must be a object literal`, node));
-    }
-    return fp.result.ok(node.arguments[1]);
-  }
-  return fp.result.ok(undefined);
-}
-function findValImageMetadataArg(node) {
-  if (node.arguments.length === 0) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.image() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.image() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (node.arguments.length === 2) {
-    if (!ts__default["default"].isObjectLiteralExpression(node.arguments[1])) {
-      return fp.result.err(new ValSyntaxError(`Invalid c.image() call: metadata must be a object literal`, node));
-    }
-    return fp.result.ok(node.arguments[1]);
-  }
-  return fp.result.ok(undefined);
-}
-function findValRemoteMetadataArg(node) {
-  if (node.arguments.length === 0) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.remote() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return fp.result.err(new ValSyntaxError(`Invalid c.remote() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (node.arguments.length === 2) {
-    if (!ts__default["default"].isObjectLiteralExpression(node.arguments[1])) {
-      return fp.result.err(new ValSyntaxError(`Invalid c.remote() call: metadata must be a object literal`, node));
-    }
-    return fp.result.ok(node.arguments[1]);
-  }
-  return fp.result.ok(undefined);
-}
-
-/**
- * Given a list of expressions, validates that all the expressions are not
- * spread elements. In other words, it ensures that the expressions are the
- * initializers of the values at their respective indices in the evaluated list.
- */
 function validateInitializers(nodes) {
   for (const node of nodes) {
     if (ts__default["default"].isSpreadElement(node)) {
@@ -358,27 +226,6 @@ function isValidIdentifier(text) {
 function createPropertyAssignment(key, value) {
   return ts__default["default"].factory.createPropertyAssignment(isValidIdentifier(key) ? ts__default["default"].factory.createIdentifier(key) : ts__default["default"].factory.createStringLiteral(key), toExpression(value));
 }
-function createValFileReference(value) {
-  const args = [ts__default["default"].factory.createStringLiteral(value[core.FILE_REF_PROP])];
-  if (value.metadata) {
-    args.push(toExpression(value.metadata));
-  }
-  return ts__default["default"].factory.createCallExpression(ts__default["default"].factory.createPropertyAccessExpression(ts__default["default"].factory.createIdentifier("c"), ts__default["default"].factory.createIdentifier("file")), undefined, args);
-}
-function createValImageReference(value) {
-  const args = [ts__default["default"].factory.createStringLiteral(value[core.FILE_REF_PROP])];
-  if (value.metadata) {
-    args.push(toExpression(value.metadata));
-  }
-  return ts__default["default"].factory.createCallExpression(ts__default["default"].factory.createPropertyAccessExpression(ts__default["default"].factory.createIdentifier("c"), ts__default["default"].factory.createIdentifier("image")), undefined, args);
-}
-function createValRemoteReference(value) {
-  const args = [ts__default["default"].factory.createStringLiteral(value[core.FILE_REF_PROP])];
-  if (value.metadata) {
-    args.push(toExpression(value.metadata));
-  }
-  return ts__default["default"].factory.createCallExpression(ts__default["default"].factory.createPropertyAccessExpression(ts__default["default"].factory.createIdentifier("c"), ts__default["default"].factory.createIdentifier("remote")), undefined, args);
-}
 
 /**
  * Builds the expression `c.json(() => import("<importPath>"))` used to reference
@@ -464,16 +311,12 @@ function toExpression(value) {
   } else if (Array.isArray(value)) {
     return ts__default["default"].factory.createArrayLiteralExpression(value.map(toExpression));
   } else if (typeof value === "object") {
-    if (isValFileValue(value)) {
-      return createValFileReference(value);
-    }
-    if (isValImageValue(value)) {
-      return createValImageReference(value);
-    }
-    if (isValRemoteValue(value)) {
-      return createValRemoteReference(value);
-    }
-    return ts__default["default"].factory.createObjectLiteralExpression(Object.entries(value).map(([key, value]) => createPropertyAssignment(key, value)));
+    return ts__default["default"].factory.createObjectLiteralExpression(Object.entries(value)
+    // `patch_id` is injected server-side onto a media source whose bytes are
+    // not committed yet. It describes the draft, not the content, and a
+    // whole-object write built from the client's optimistic view would
+    // otherwise print it into the user's file.
+    .filter(([key]) => key !== "patch_id").map(([key, value]) => createPropertyAssignment(key, value)));
   } else {
     return ts__default["default"].factory.createStringLiteral(value);
   }
@@ -606,63 +449,6 @@ function replaceInNode(document, node, key, value) {
       }
       return fp.result.ok(assignment);
     }), fp.result.map(assignment => replaceNodeValue(document, assignment.initializer, value)));
-  } else if (isValFileMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return fp.result.err(new patch.PatchError("Cannot replace c.file reference with non-string value"));
-      }
-      return fp.pipe(findValFileNodeArg(node), fp.result.map(refNode => replaceNodeValue(document, refNode, value)));
-    } else {
-      return fp.pipe(findValFileMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot replace in c.file metadata when it does not exist"));
-        }
-        if (key !== "metadata") {
-          return fp.result.err(new patch.PatchError(`Cannot replace c.file metadata key ${key} when it does not exist`));
-        }
-        return replaceInNode(document,
-        // TODO: creating a fake object here might not be right - seems to work though
-        ts__default["default"].factory.createObjectLiteralExpression([ts__default["default"].factory.createPropertyAssignment(key, metadataArgNode)]), key, value);
-      }));
-    }
-  } else if (isValImageMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return fp.result.err(new patch.PatchError("Cannot replace c.image reference with non-string value"));
-      }
-      return fp.pipe(findValImageNodeArg(node), fp.result.map(refNode => replaceNodeValue(document, refNode, value)));
-    } else {
-      return fp.pipe(findValImageMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot replace in c.image metadata when it does not exist"));
-        }
-        if (key !== "metadata") {
-          return fp.result.err(new patch.PatchError(`Cannot replace c.image metadata key ${key} when it does not exist`));
-        }
-        return replaceInNode(document,
-        // TODO: creating a fake object here might not be right - seems to work though
-        ts__default["default"].factory.createObjectLiteralExpression([ts__default["default"].factory.createPropertyAssignment(key, metadataArgNode)]), key, value);
-      }));
-    }
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return fp.result.err(new patch.PatchError("Cannot replace c.image reference with non-string value"));
-      }
-      return fp.pipe(findValRemoteNodeArg(node), fp.result.map(refNode => replaceNodeValue(document, refNode, value)));
-    } else {
-      return fp.pipe(findValRemoteMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot replace in c.remote metadata when it does not exist"));
-        }
-        if (key !== "metadata") {
-          return fp.result.err(new patch.PatchError(`Cannot replace c.remote metadata key ${key} when it does not exist`));
-        }
-        return replaceInNode(document,
-        // TODO: creating a fake object here might not be right - seems to work though
-        ts__default["default"].factory.createObjectLiteralExpression([ts__default["default"].factory.createPropertyAssignment(key, metadataArgNode)]), key, value);
-      }));
-    }
   } else {
     return fp.result.err(shallowValidateExpression(node) ?? new patch.PatchError("Cannot replace in non-object/array"));
   }
@@ -679,21 +465,6 @@ function getFromNode(node, key) {
     return fp.pipe(parseAndValidateArrayInboundsIndex(key, node.elements), fp.result.map(index => node.elements[index]));
   } else if (ts__default["default"].isObjectLiteralExpression(node)) {
     return fp.pipe(findObjectPropertyAssignment(node, key), fp.result.map(assignment => assignment === null || assignment === void 0 ? void 0 : assignment.initializer));
-  } else if (isValFileMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return findValFileNodeArg(node);
-    }
-    return findValFileMetadataArg(node);
-  } else if (isValImageMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return findValImageNodeArg(node);
-    }
-    return findValImageMetadataArg(node);
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return findValRemoteNodeArg(node);
-    }
-    return findValRemoteMetadataArg(node);
   } else {
     return fp.result.err(shallowValidateExpression(node) ?? new patch.PatchError("Cannot access non-object/array"));
   }
@@ -726,39 +497,6 @@ function removeFromNode(document, node, key) {
       }
       return fp.result.ok(assignment);
     }), fp.result.map(assignment => [removeAt(document, node.properties, node.properties.indexOf(assignment))[0], assignment.initializer]));
-  } else if (isValFileMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return fp.result.err(new patch.PatchError("Cannot remove a ref from c.file"));
-    } else {
-      return fp.pipe(findValFileMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot remove from c.file metadata when it does not exist"));
-        }
-        return removeFromNode(document, metadataArgNode, key);
-      }));
-    }
-  } else if (isValImageMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return fp.result.err(new patch.PatchError("Cannot remove a ref from c.image"));
-    } else {
-      return fp.pipe(findValImageMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot remove from c.image metadata when it does not exist"));
-        }
-        return removeFromNode(document, metadataArgNode, key);
-      }));
-    }
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return fp.result.err(new patch.PatchError("Cannot remove a ref from c.remote"));
-    } else {
-      return fp.pipe(findValRemoteMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot remove from c.remote metadata when it does not exist"));
-        }
-        return removeFromNode(document, metadataArgNode, key);
-      }));
-    }
   } else {
     return fp.result.err(shallowValidateExpression(node) ?? new patch.PatchError("Cannot remove from non-object/array"));
   }
@@ -766,22 +504,10 @@ function removeFromNode(document, node, key) {
 function removeAtPath(document, rootNode, path) {
   return fp.pipe(getPointerFromPath(rootNode, path), fp.result.flatMap(([node, key]) => removeFromNode(document, node, key)));
 }
-function isValFileValue(value) {
-  return !!(typeof value === "object" && value && core.VAL_EXTENSION in value && value[core.VAL_EXTENSION] === "file" && core.FILE_REF_PROP in value && typeof value[core.FILE_REF_PROP] === "string" && value[core.FILE_REF_SUBTYPE_TAG] !== "image");
-}
-function isValImageValue(value) {
-  return !!(typeof value === "object" && value && core.VAL_EXTENSION in value && value[core.VAL_EXTENSION] === "file" && core.FILE_REF_PROP in value && typeof value[core.FILE_REF_PROP] === "string" && value[core.FILE_REF_SUBTYPE_TAG] === "image");
-}
-function isValRemoteValue(value) {
-  return !!(typeof value === "object" && value && core.VAL_EXTENSION in value && value[core.VAL_EXTENSION] === "remote" && core.FILE_REF_PROP in value && typeof value[core.FILE_REF_PROP] === "string");
-}
 function addToNode(document, node, key, value) {
   if (ts__default["default"].isArrayLiteralExpression(node)) {
     return fp.pipe(parseAndValidateArrayInsertIndex(key, node.elements), fp.result.map(index => [insertAt(document, node.elements, index, toExpression(value))]));
   } else if (ts__default["default"].isObjectLiteralExpression(node)) {
-    if (key === core.FILE_REF_PROP) {
-      return fp.result.err(new patch.PatchError("Cannot add a key ref to object"));
-    }
     return fp.pipe(findObjectPropertyAssignment(node, key), fp.result.map(assignment => {
       if (!assignment) {
         return [insertAt(document, node.properties, node.properties.length, createPropertyAssignment(key, value))];
@@ -789,57 +515,6 @@ function addToNode(document, node, key, value) {
         return replaceNodeValue(document, assignment.initializer, value);
       }
     }));
-  } else if (isValFileMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return fp.result.err(new patch.PatchError(`Cannot add ${core.FILE_REF_PROP} key to c.file with non-string value`));
-      }
-      return fp.pipe(findValFileNodeArg(node), fp.result.map(arg => replaceNodeValue(document, arg, value)));
-    } else {
-      return fp.pipe(findValFileMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot add metadata to c.file when it already exists"));
-        }
-        if (key !== "metadata") {
-          return fp.result.err(new patch.PatchError(`Cannot add ${key} key to c.file: only metadata is allowed`));
-        }
-        return fp.result.ok([insertAt(document, node.arguments, node.arguments.length, toExpression(value))]);
-      }));
-    }
-  } else if (isValImageMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return fp.result.err(new patch.PatchError(`Cannot add ${core.FILE_REF_PROP} key to c.image with non-string value`));
-      }
-      return fp.pipe(findValImageNodeArg(node), fp.result.map(arg => replaceNodeValue(document, arg, value)));
-    } else {
-      return fp.pipe(findValImageMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot add metadata to c.image when it already exists"));
-        }
-        if (key !== "metadata") {
-          return fp.result.err(new patch.PatchError(`Cannot add ${key} key to c.image: only metadata is allowed`));
-        }
-        return fp.result.ok([insertAt(document, node.arguments, node.arguments.length, toExpression(value))]);
-      }));
-    }
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === core.FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return fp.result.err(new patch.PatchError(`Cannot add ${core.FILE_REF_PROP} key to c.remote with non-string value`));
-      }
-      return fp.pipe(findValRemoteNodeArg(node), fp.result.map(arg => replaceNodeValue(document, arg, value)));
-    } else {
-      return fp.pipe(findValRemoteMetadataArg(node), fp.result.flatMap(metadataArgNode => {
-        if (metadataArgNode) {
-          return fp.result.err(new patch.PatchError("Cannot add metadata to c.remote when it already exists"));
-        }
-        if (key !== "metadata") {
-          return fp.result.err(new patch.PatchError(`Cannot add ${key} key to c.remote: only metadata is allowed`));
-        }
-        return fp.result.ok([insertAt(document, node.arguments, node.arguments.length, toExpression(value))]);
-      }));
-    }
   } else {
     return fp.result.err(shallowValidateExpression(node) ?? new patch.PatchError("Cannot add to non-object/array"));
   }
@@ -1421,7 +1096,10 @@ function rebaseContentOp(op, prefixLen) {
         from: op.from.slice(prefixLen)
       });
     case "file":
-      return fp.result.err(new patch.PatchError("Cannot apply a file op to a jsonValues entry"));
+      // A file op carries bytes, not content. The binary goes through the
+      // normal upload pipeline; what lands in the entry is the `patch_id` that
+      // marks the bytes as not yet committed, which the caller writes.
+      return fp.result.err(new patch.PatchError("A file op is not a content op: rebase it via its path"));
   }
 }
 
@@ -1455,9 +1133,6 @@ function applyJsonValuesEntryPatches(args) {
   } of patches) {
     let touched = false;
     for (const op of patch$1) {
-      if (op.op === "file") {
-        continue;
-      }
       const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
         kind: "normal"
       };
@@ -1465,6 +1140,32 @@ function applyJsonValuesEntryPatches(args) {
         continue;
       }
       touched = true;
+      // A file op does not edit the entry's content — its bytes go through the
+      // upload pipeline. What the entry needs is the `patch_id` saying those
+      // bytes are not committed yet, so `mediaUrl` serves them from the patch
+      // directory instead of a `/public` path that holds nothing. Without this a
+      // just-uploaded image inside an entry renders broken.
+      if (op.op === "file") {
+        if (op.value === null || content === undefined) {
+          // A delete carries no bytes to point at, and there is nothing to mark
+          // on an entry that does not exist.
+          continue;
+        }
+        const applied = patch.applyPatch(patch.deepClone(content), jsonOps$1, [{
+          op: "add",
+          path: cls.subPath.concat(...(op.nestedFilePath ?? [])).concat("patch_id"),
+          value: patchId
+        }]);
+        if (fp.result.isErr(applied)) {
+          return {
+            kind: "error",
+            message: applied.error.message,
+            patchId
+          };
+        }
+        content = applied.value;
+        continue;
+      }
       if (cls.subPath.length === 0) {
         if (op.op === "add" || op.op === "replace") {
           content = op.value;
@@ -2437,6 +2138,17 @@ class ValOps {
         const serializedSchema = jsonValuesSchemaFor(path);
         for (const op of patchData.patch) {
           if (op.op === "file") {
+            // A file op inside a `.jsonValues()` entry has nothing to inject
+            // HERE: the entry is an opaque marker in the module source, so an
+            // `add` reaching into it fails and poisons the rest of this
+            // module's chain. `applyJsonValuesEntryPatches` writes the patch_id
+            // into the entry's draft content instead.
+            const fileCls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+              kind: "normal"
+            };
+            if (fileCls.kind === "entry" && fileCls.subPath.length > 0) {
+              continue;
+            }
             if (op.value !== null) {
               // NOTE: We insert the last patch_id that modify a file
               // when constructing the url we use the patch id (and the file path)
@@ -2737,7 +2449,7 @@ class ValOps {
         };
       }
       const type = schemaAtPath instanceof core.ImageSchema ? "image" : "file";
-      const filePath = value[core.FILE_REF_PROP];
+      const filePath = value.path;
       const fileData = (fileLastUpdatedByPatchId === null || fileLastUpdatedByPatchId === void 0 ? void 0 : fileLastUpdatedByPatchId[filePath]) || null;
       let metadata;
       let metadataErrors;
@@ -2779,23 +2491,14 @@ class ValOps {
           }]
         };
       }
-      const metadataSourcePath = core.Internal.createValPathOfItem(sourcePath, "metadata");
-      if (!metadataSourcePath) {
-        throw new Error("Could not create metadata path");
-      }
-      const currentValueMetadata = value.metadata;
-      if (!currentValueMetadata) {
-        return {
-          [metadataSourcePath]: [{
-            message: "Missing metadata field: 'metadata'",
-            value
-          }]
-        };
-      }
+      // The fields Val computes from the bytes sit next to `path` now, so the
+      // error is reported at the field it is about rather than at a `metadata`
+      // object that no longer exists.
+      const currentValueMetadata = value;
       const fieldErrors = {};
       for (const field of getFieldsForType(type)) {
         const fieldMetadata = metadata[field];
-        const fieldSourcePath = core.Internal.createValPathOfItem(metadataSourcePath, field);
+        const fieldSourcePath = core.Internal.createValPathOfItem(sourcePath, field);
         if (!fieldSourcePath) {
           throw new Error("Could not create field path");
         }
@@ -3387,11 +3090,15 @@ function isOnlyFileCheckValidationError(validationError) {
   }
   return false;
 }
+
+/**
+ * Whether a flagged validation value is media.
+ *
+ * The caller already knows the schema said image or file — this only guards
+ * against a value that never got that far.
+ */
 function isFileSource(value) {
-  if (typeof value === "object" && value !== null && core.FILE_REF_PROP in value && core.VAL_EXTENSION in value && value[core.VAL_EXTENSION] === "file" && core.FILE_REF_PROP) {
-    return true;
-  }
-  return false;
+  return typeof value === "object" && value !== null && "path" in value && typeof value.path === "string";
 }
 function formatPatchSourceError(error) {
   if ("message" in error) {
@@ -3596,119 +3303,1114 @@ 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.
+ *
+ * ## Why a log and not links between the patches
  *
- * NOTE: patches that will be deleted are not included in the changed patches, since they will be deleted any how.
+ * 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.
  *
- * @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.
+ * 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
-          };
-        }
-      }
-    } else {
-      lastNonDeletedPatchIndex = i;
-    }
+
+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 {
-    changedPatches
+    patchId,
+    createdAt,
+    path
   };
 }
-
-async function uploadRemoteFile(contentHost, project, bucket, fileHash, fileExt, fileBuffer, auth) {
-  const authHeader = "apiKey" in auth ? {
-    Authorization: `Bearer ${auth.apiKey}`
-  } : {
-    "x-val-pat": auth.pat
-  };
-  const res = await fetch(`${contentHost}/v1/${project}/remote/files/b/${bucket}/f/${fileHash}.${fileExt}`, {
-    method: "PUT",
-    headers: {
-      ...authHeader,
-      "Content-Type": "application/octet-stream"
-    },
-    body: new Uint8Array(fileBuffer)
-  });
-  if (!res.ok) {
-    var _res$headers$get;
-    if (res.status === 409) {
-      // File already exists
-      return {
-        success: true
-      };
-    }
-    if ((_res$headers$get = res.headers.get("content-type")) !== null && _res$headers$get !== void 0 && _res$headers$get.includes("application/json")) {
-      const json = await res.json();
-      const message = internal.getErrorMessageFromUnknownJson(json, JSON.stringify(json));
+function serializePatchLog(entries) {
+  return [HEADER, ...entries.map(formatPatchLogLine), ""].join("\n");
+}
+function readPatchLog(logFilePath) {
+  let raw;
+  try {
+    raw = fs__default["default"].readFileSync(logFilePath, "utf-8");
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT") {
       return {
-        success: false,
-        error: `Failed to upload remote file: ${message}.`
+        status: "absent"
       };
     }
     return {
-      success: false,
-      error: `An unexpected error occurred while uploading remote file. HTTP status was: ${await res.text()}.`
+      status: "unreadable",
+      message: `Could not read ${logFilePath}: ${err instanceof Error ? err.message : "unknown error"}`
     };
   }
-  return {
-    success: true
-  };
+  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
+    });
+  }
 
-function getFileExt(filePath) {
-  // NOTE: We do not import the path module. This code is copied in different projects. We want the same implementation and which means that this might running in browser where path is not available).
-  return filePath.split(".").pop() || "";
+  // 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
+  };
 }
 
-/** Serializes a schema, or gives up quietly — serialization errors are reported elsewhere. */
-function serializeSchemaSafely(schema) {
+/**
+ * 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 {
-    return schema === null || schema === void 0 ? void 0 : schema["executeSerialize"]();
+    fd = fs__default["default"].openSync(dirPath, "r");
+    fs__default["default"].fsyncSync(fd);
   } catch {
-    return undefined;
+    // ignore: see above
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs__default["default"].closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
   }
 }
-class ValOpsFS extends ValOps {
-  static VAL_DIR = ".val";
-  constructor(contentUrl, rootDir, valModules, options) {
-    super(valModules, options);
-    this.contentUrl = contentUrl;
-    this.rootDir = rootDir;
-    this.host = new FSOpsHost();
-    this.jsonEntryFilesFingerprint = new JsonEntryFilesFingerprint(rootDir);
+
+/**
+ * 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__namespace["default"].dirname(logFilePath);
+  fs__default["default"].mkdirSync(dirPath, {
+    recursive: true
+  });
+  if (!fs__default["default"].existsSync(logFilePath)) {
+    writePatchLogFile(logFilePath, []);
+  }
+  const fd = fs__default["default"].openSync(logFilePath, "a");
+  try {
+    fs__default["default"].writeSync(fd, `${formatPatchLogLine(entry)}\n`);
+    fs__default["default"].fsyncSync(fd);
+  } finally {
+    fs__default["default"].closeSync(fd);
   }
+}
 
-  /**
-   * Change detection for `.jsonValues()` entry files, which no sha can see (their
-   * content lives behind a thunk that `JSON.stringify` drops).
+/**
+ * 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__namespace["default"].dirname(logFilePath);
+  fs__default["default"].mkdirSync(dirPath, {
+    recursive: true
+  });
+  const tmpPath = `${logFilePath}.tmp-${process.pid}`;
+  const fd = fs__default["default"].openSync(tmpPath, "w");
+  try {
+    fs__default["default"].writeSync(fd, serializePatchLog(entries));
+    fs__default["default"].fsyncSync(fd);
+  } finally {
+    fs__default["default"].closeSync(fd);
+  }
+  fs__default["default"].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.z.object({
+  path: z.z.string().refine(p => p.startsWith("/") && p.includes(".val."), "Path is not valid. Must start with '/' and include '.val.'"),
+  patch: internal.Patch,
+  patchId: z.z.string(),
+  baseSha: z.z.string().refine(p => true),
+  authorId: z.z.string().refine(p => true).nullable(),
+  createdAt: z.z.string().datetime(),
+  coreVersion: z.z.string().nullable(),
+  sessionId: z.z.string().nullable()
+});
+const FSPatchBase = z.z.object({
+  baseSha: z.z.string().refine(p => true),
+  timestamp: z.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__namespace["default"].join(patchesDir, PATCH_LOG_FILE_NAME);
+}
+function patchRepairLogFile(patchesDir) {
+  return path__namespace["default"].join(patchesDir, PATCH_REPAIR_LOG_FILE_NAME);
+}
+function patchDir(patchesDir, patchId) {
+  return path__namespace["default"].join(patchesDir, patchId);
+}
+function patchRecordFile(patchesDir, patchId) {
+  return path__namespace["default"].join(patchDir(patchesDir, patchId), "patch.json");
+}
+function patchBaseFile(patchesDir, patchId) {
+  return path__namespace["default"].join(patchDir(patchesDir, patchId), "base.json");
+}
+function patchBinaryFile(patchesDir, patchId, filePath) {
+  return path__namespace["default"].join(patchDir(patchesDir, patchId), "files", filePath, path__namespace["default"].basename(filePath));
+}
+function patchBinaryFileMetadata(patchesDir, patchId, filePath) {
+  return path__namespace["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__default["default"].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: zodValidationError.fromError(parsed.error).toString()
+    };
+  }
+  return {
+    data: parsed.data
+  };
+}
+function listPatchDirNames(patchesDir) {
+  return fs__default["default"].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__default["default"].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__default["default"].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__namespace["default"].join(patchesDir, name),
+        message: read.error
+      });
+    } else {
+      problems.push({
+        type: "orphan-directory",
+        name,
+        dir: path__namespace["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__default["default"].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__namespace["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__default["default"].mkdirSync(dir, {
+    recursive: true
+  });
+  const file = patchRecordFile(patchesDir, patchId);
+  const tmpFile = `${file}.tmp-${process.pid}`;
+  const fd = fs__default["default"].openSync(tmpFile, "w");
+  try {
+    fs__default["default"].writeSync(fd, JSON.stringify(record));
+    fs__default["default"].fsyncSync(fd);
+  } finally {
+    fs__default["default"].closeSync(fd);
+  }
+  fs__default["default"].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__default["default"].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__default["default"].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__default["default"].existsSync(patchesDir)) {
+    return {
+      movedTo: patchesDir
+    };
+  }
+  const movedTo = `${patchesDir}-corrupt-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  try {
+    fs__default["default"].renameSync(patchesDir, movedTo);
+  } catch (err) {
+    return {
+      error: `Could not move ${patchesDir} aside: ${err instanceof Error ? err.message : "unknown error"}`
+    };
+  }
+  try {
+    fs__default["default"].mkdirSync(patchesDir, {
+      recursive: true
+    });
+    fs__default["default"].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__default["default"].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__default["default"].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__default["default"].writeSync(fd, formatPatchLockInfo(info));
+    fs__default["default"].fsyncSync(fd);
+  } finally {
+    fs__default["default"].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__default["default"].mkdirSync(path__namespace["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__default["default"].randomUUID(),
+      pid: process.pid,
+      host: os__default["default"].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__default["default"].unlinkSync(lockFilePath);
+        } catch {
+          // Someone else got there first, which is the outcome we wanted anyway.
+        }
+      }
+      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);
+  }
+}
+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__default["default"].openSync(lockFilePath, "w");
+      try {
+        fs__default["default"].writeSync(fd, formatPatchLockInfo(next));
+        fs__default["default"].fsyncSync(fd);
+      } finally {
+        fs__default["default"].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__default["default"].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) {
+  const authHeader = "apiKey" in auth ? {
+    Authorization: `Bearer ${auth.apiKey}`
+  } : {
+    "x-val-pat": auth.pat
+  };
+  const res = await fetch(`${contentHost}/v1/${project}/remote/files/b/${bucket}/f/${fileHash}.${fileExt}`, {
+    method: "PUT",
+    headers: {
+      ...authHeader,
+      "Content-Type": "application/octet-stream"
+    },
+    body: new Uint8Array(fileBuffer)
+  });
+  if (!res.ok) {
+    var _res$headers$get;
+    if (res.status === 409) {
+      // File already exists
+      return {
+        success: true
+      };
+    }
+    if ((_res$headers$get = res.headers.get("content-type")) !== null && _res$headers$get !== void 0 && _res$headers$get.includes("application/json")) {
+      const json = await res.json();
+      const message = internal.getErrorMessageFromUnknownJson(json, JSON.stringify(json));
+      return {
+        success: false,
+        error: `Failed to upload remote file: ${message}.`
+      };
+    }
+    return {
+      success: false,
+      error: `An unexpected error occurred while uploading remote file. HTTP status was: ${await res.text()}.`
+    };
+  }
+  return {
+    success: true
+  };
+}
+
+function getFileExt(filePath) {
+  // NOTE: We do not import the path module. This code is copied in different projects. We want the same implementation and which means that this might running in browser where path is not available).
+  return filePath.split(".").pop() || "";
+}
+
+/** Serializes a schema, or gives up quietly — serialization errors are reported elsewhere. */
+function serializeSchemaSafely(schema) {
+  try {
+    return schema === null || schema === void 0 ? void 0 : schema["executeSerialize"]();
+  } catch {
+    return undefined;
+  }
+}
+class ValOpsFS extends ValOps {
+  static VAL_DIR = ".val";
+  constructor(contentUrl, rootDir, valModules, options) {
+    super(valModules, options);
+    this.contentUrl = contentUrl;
+    this.rootDir = rootDir;
+    this.host = new FSOpsHost();
+    this.jsonEntryFilesFingerprint = new JsonEntryFilesFingerprint(rootDir);
+  }
+
+  /**
+   * Change detection for `.jsonValues()` entry files, which no sha can see (their
+   * 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
   }
@@ -3802,14 +4504,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
@@ -3824,6 +4540,7 @@ class ValOpsFS extends ValOps {
           schemaSha: currentSchemaSha,
           sourcesSha: currentSourcesSha,
           patches,
+          ...removedNotice,
           jsonEntriesSha: currentJsonEntriesSha
         };
       }
@@ -3948,6 +4665,7 @@ class ValOpsFS extends ValOps {
         schemaSha: currentSchemaSha,
         sourcesSha: currentSourcesSha,
         patches,
+        ...removedNotice,
         jsonEntriesSha: currentJsonEntriesSha
       };
     } catch (err) {
@@ -3967,134 +4685,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__namespace["default"].basename(path__namespace["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 {
+          status: "error",
+          message: current.message
+        };
+      }
+      if (current.problems.length === 0) {
         return {
-          ...patchData,
-          patch: undefined
+          status: "ok",
+          entries: current.entries
         };
       }
-      return patchData;
-    }).filter(patchData => {
-      if (filters.patchIds && filters.patchIds.length > 0) {
-        return filters.patchIds.includes(patchData.patchId);
+      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}.`);
+        }
       }
-      return true;
+      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)) {
@@ -4169,53 +4905,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: core.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 fp.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: core.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 fp.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 fp.result.ok({
         patchId
       });
-    } catch (err) {
-      if (err instanceof Error) {
-        return fp.result.err({
-          errorType: "other",
-          error: err,
-          message: err.message
-        });
-      }
+    });
+    if (locked.status !== "ok") {
       return fp.result.err({
         errorType: "other",
-        error: err,
-        message: "Unknown error"
+        message: locked.message
       });
     }
+    return locked.value;
   }
   async getSourceFile(path) {
     const filePath = path__namespace["default"].join(this.rootDir, path);
@@ -4252,10 +4995,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);
@@ -4295,15 +5042,7 @@ class ValOpsFS extends ValOps {
     }
   }
   async getBase64EncodedBinaryFileMetadataFromPatch(filePath, type, patchId) {
-    const patchDirRes = await this.getParentPatchIdFromPatchId(patchId);
-    if (fp.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: [{
@@ -4339,95 +5078,132 @@ class ValOpsFS extends ValOps {
     };
   }
   async getBase64EncodedBinaryFileFromPatch(filePath, patchId) {
-    const patchDirRes = await this.getParentPatchIdFromPatchId(patchId);
-    if (!fp.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 (fp.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__default["default"].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: "Failed to get patch dir map"
+          message: locked.message
         }
       };
     }
-    const currentPatches = this.createPatchChain((await this.fetchPatchesFromFS(false)).patches);
-    this.updateOrderedPatches(computeChangedPatchParentRefs(currentPatches, patchIds), patchDirMapRes.value, patchIds);
+    if (locked.value.status === "error") {
+      return {
+        error: {
+          message: locked.value.message
+        }
+      };
+    }
+    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__namespace["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__default["default"].existsSync(patchesDir)) {
+        return {};
+      }
+      const tmpDir = path__namespace["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 = [];
@@ -4490,30 +5266,13 @@ class ValOpsFS extends ValOps {
         uploadedRemoteRefs.push(ref);
       }
     }
-    const patchIdToPatchDirMapRes = await this.getParentPatchIdFromPatchIdMap();
-    if (fp.result.isErr(patchIdToPatchDirMapRes)) {
-      return {
-        updatedFiles,
-        uploadedRemoteRefs,
-        errors
-      };
-    }
-    const patchIdToPatchDirMap = patchIdToPatchDirMapRes.value;
     for (const [ref, {
       patchId
     }] of localFileDescriptors) {
       const filePath = ref;
       const absPath = path__namespace["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] = {
@@ -4543,14 +5302,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) {
@@ -4595,47 +5347,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 fp.result.err("failed-to-read-patches");
-    }
-    const patch = patches.patches[patchId];
-    if (!patch) {
-      console.error("Could not find patch with patchId: ", patchId);
-      return fp.result.err("patch-not-found");
-    }
-    return fp.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 fp.result.err("failed-to-read-patches");
-    }
-    return fp.result.ok(Object.fromEntries(Object.entries(patches.patches).map(([patchId, value]) => [patchId, this.getParentPatchIdFromParentRef(value.parentRef)])));
-  }
 
   // #region fs file path helpers
   getPatchesDir() {
     return path__namespace["default"].join(this.rootDir, ValOpsFS.VAL_DIR, "patches");
   }
-  getFullPatchDir(patchDir) {
-    return path__namespace["default"].join(this.getPatchesDir(), patchDir);
-  }
-  getBinaryFilePath(filePath, patchDir) {
-    return path__namespace["default"].join(this.getFullPatchDir(patchDir), "files", filePath, path__namespace["default"].basename(filePath));
-  }
-  getBinaryFileMetadataPath(filePath, patchDir) {
-    return path__namespace["default"].join(this.getFullPatchDir(patchDir), "files", filePath, "metadata.json");
-  }
-  getPatchFilePath(patchDir) {
-    return path__namespace["default"].join(this.getFullPatchDir(patchDir), "patch.json");
-  }
-  getPatchBaseFile(patchDir) {
-    return path__namespace["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__namespace["default"].join(this.rootDir, ValOpsFS.VAL_DIR, PATCH_LOCK_FILE_NAME);
   }
 }
 class FSOpsHost {
@@ -4715,27 +5438,11 @@ class FSOpsHost {
     fs__default["default"].mkdirSync(path__namespace["default"].dirname(to), {
       recursive: true
     });
-    fs__default["default"].copyFileSync(from, to);
-  }
-}
-const FSPatch = z.z.object({
-  path: z.z.string().refine(p => p.startsWith("/") && p.includes(".val."), "Path is not valid. Must start with '/' and include '.val.'"),
-  patch: internal.Patch,
-  patchId: z.z.string(),
-  baseSha: z.z.string(),
-  parentRef: internal.ParentRef,
-  authorId: z.z.string().refine(p => true).nullable(),
-  createdAt: z.z.string().datetime(),
-  coreVersion: z.z.string().nullable(),
-  // TODO: use this to check if patch is compatible with current core version?
-  sessionId: z.z.string().nullable()
-});
-const FSPatchBase = z.z.object({
-  baseSha: z.z.string().refine(p => true),
-  timestamp: z.z.string().datetime()
-});
+    fs__default["default"].copyFileSync(from, to);
+  }
+}
 
-const textEncoder$1 = new TextEncoder();
+const textEncoder$2 = new TextEncoder();
 const PatchId = z.z.string().refine(s => !!s); // TODO: validate
 const CommitSha = z.z.string().refine(s => !!s); // TODO: validate
 z.z.string().refine(s => !!s); // TODO: validate
@@ -5426,7 +6133,7 @@ class ValOpsHttp extends ValOps {
     });
     params.set("body_sha",
     // We use this for cache invalidation
-    core.Internal.getSHA256Hash(textEncoder$1.encode(stringifiedFiles)));
+    core.Internal.getSHA256Hash(textEncoder$2.encode(stringifiedFiles)));
     return fetch(`${this.contentUrl}/v1/${this.project}/files?${params}`, {
       method: "PUT",
       // Yes, PUT is weird. Weirder to have a body in a GET request.
@@ -6759,7 +7466,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 {
@@ -9154,15 +9861,21 @@ _input // TODO: use buffer to determine mimetype
   };
 }
 
+/**
+ * The media path a validation error is about, if it is about media at all.
+ *
+ * There is no schema in hand here — a `ValidationError` carries only the value
+ * it flagged — so the shape is all there is to go on.
+ */
 function getValidationErrorFileRef(validationError) {
-  const maybeRef = validationError.value && typeof validationError.value === "object" && core.FILE_REF_PROP in validationError.value && typeof validationError.value[core.FILE_REF_PROP] === "string" ? validationError.value[core.FILE_REF_PROP] : undefined;
-  if (!maybeRef) {
+  const maybePath = validationError.value && typeof validationError.value === "object" && "path" in validationError.value && typeof validationError.value.path === "string" ? validationError.value.path : undefined;
+  if (!maybePath) {
     return null;
   }
-  return maybeRef;
+  return maybePath;
 }
 
-const textEncoder = new TextEncoder();
+const textEncoder$1 = new TextEncoder();
 async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
   const remoteRefDataRes = core.Internal.remote.splitRemoteRef(ref);
   if (remoteRefDataRes.status === "error") {
@@ -9192,10 +9905,10 @@ async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
   const fileExt = getFileExt(relativeFilePath);
   const currentValidationHash = core.Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata,
   // TODO: validate
-  fileHash, textEncoder);
+  fileHash, textEncoder$1);
   const validationHashFromRemoteRefValues = core.Internal.remote.getValidationHash(remoteRefDataRes.version, schema, getFileExt(remoteRefDataRes.filePath), metadata,
   // TODO: validate
-  fileHash, textEncoder);
+  fileHash, textEncoder$1);
   if (
   // Current validation hash is the same as the remote validation hash
   // We assume the uploaded file exists and is correct
@@ -9241,7 +9954,7 @@ async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
     ...metadata,
     ...currentMetadata
   };
-  const nextValidationHash = core.Internal.remote.getValidationHash(coreVersion, schema, fileExt, updatedMetadata, fileBufferRes.fileHash, textEncoder);
+  const nextValidationHash = core.Internal.remote.getValidationHash(coreVersion, schema, fileExt, updatedMetadata, fileBufferRes.fileHash, textEncoder$1);
   if (!updatedMetadata.mimeType) {
     return {
       status: "error",
@@ -9371,6 +10084,36 @@ function parentPatchPathOfMediaEntry(sourcePath, entryKey) {
 }
 
 // TODO: find a better name? transformFixesToPatch?
+/**
+ * A whole media value, for the fixes that replace one outright.
+ *
+ * The three remote fixes each wrote this shape out by hand, and one of them was
+ * left behind when the shape changed. One name, so the next change cannot miss a
+ * site.
+ *
+ * `path` last is deliberate: it is the field the fix is about, and a stray
+ * `path` inside the metadata must not win over it.
+ */
+function mediaValue(path, metadata) {
+  const fields = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : {};
+  return {
+    ...fields,
+    path
+  };
+}
+
+/**
+ * The media value a validation error flagged, read as a plain record.
+ *
+ * A `ValidationError` carries only a value, never the schema that rejected it,
+ * so the shape is all there is to go on here.
+ */
+function mediaValueOf(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  return value;
+}
 async function createFixPatch(config, apply, sourcePath, validationError, remoteFiles, moduleSource, moduleSchema) {
   const remainingErrors = [];
   const patch$1 = [];
@@ -9384,57 +10127,38 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
           fixes: undefined
         });
       } else if (fix === "image:check-metadata") {
-        const currentValue = validationError.value;
-        const metadataIsCorrect =
-        // metadata is a prop that is an object
-        typeof currentValue === "object" && currentValue && "metadata" in currentValue && currentValue.metadata && typeof currentValue.metadata === "object" &&
-        // width is correct
-        "width" in currentValue.metadata && currentValue.metadata.width === imageMetadata.width &&
-        // height is correct
-        "height" in currentValue.metadata && currentValue.metadata.height === imageMetadata.height &&
-        // mimeType is correct
-        "mimeType" in currentValue.metadata && currentValue.metadata.mimeType === imageMetadata.mimeType;
-        // skips if the metadata is already correct
-        if (!metadataIsCorrect) {
+        const currentValue = mediaValueOf(validationError.value);
+        const derived = {
+          width: imageMetadata.width,
+          height: imageMetadata.height,
+          mimeType: imageMetadata.mimeType
+        };
+        // One op per field, not one for the whole object: `alt` and `hotspot`
+        // are authored and sit next to these, so a whole-object write would
+        // throw away what a person typed.
+        const wrong = Object.entries(derived).filter(([field, expected]) => (currentValue === null || currentValue === void 0 ? void 0 : currentValue[field]) !== expected);
+        if (wrong.length > 0) {
           if (apply) {
-            patch$1.push({
-              op: "replace",
-              path: patch.sourceToPatchPath(sourcePath).concat("metadata"),
-              value: {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                ...currentValue.metadata,
-                width: imageMetadata.width,
-                height: imageMetadata.height,
-                mimeType: imageMetadata.mimeType
-              }
-            });
-          } else {
-            if (typeof currentValue === "object" && currentValue && "metadata" in currentValue && currentValue.metadata && typeof currentValue.metadata === "object") {
-              if (!("width" in currentValue.metadata) || currentValue.metadata.width !== imageMetadata.width) {
-                remainingErrors.push({
-                  message: "Image metadata width is incorrect! Found: " + ("width" in currentValue.metadata ? currentValue.metadata.width : "<empty>") + ". Expected: " + imageMetadata.width,
-                  fixes: undefined
-                });
-              }
-              if (!("height" in currentValue.metadata) || currentValue.metadata.height !== imageMetadata.height) {
-                remainingErrors.push({
-                  message: "Image metadata height is incorrect! Found: " + ("height" in currentValue.metadata ? currentValue.metadata.height : "<empty>") + ". Expected: " + imageMetadata.height,
-                  fixes: undefined
-                });
-              }
-              if (!("mimeType" in currentValue.metadata) || currentValue.metadata.mimeType !== imageMetadata.mimeType) {
-                remainingErrors.push({
-                  message: "Image metadata mimeType is incorrect! Found: " + ("mimeType" in currentValue.metadata ? currentValue.metadata.mimeType : "<empty>") + ". Expected: " + imageMetadata.mimeType,
-                  fixes: undefined
-                });
-              }
-            } else {
+            for (const [field, expected] of wrong) {
+              patch$1.push({
+                op: "add",
+                path: patch.sourceToPatchPath(sourcePath).concat(field),
+                value: expected
+              });
+            }
+          } else if (currentValue) {
+            for (const [field, expected] of wrong) {
               remainingErrors.push({
-                ...validationError,
-                message: "Image metadata is not an object!",
+                message: `Image ${field} is incorrect! Found: ` + (currentValue[field] ?? "<empty>") + ". Expected: " + expected,
                 fixes: undefined
               });
             }
+          } else {
+            remainingErrors.push({
+              ...validationError,
+              message: "Image is not an object!",
+              fixes: undefined
+            });
           }
         }
       } else if (fix === "image:add-metadata") {
@@ -9445,14 +10169,19 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
             fixes: undefined
           });
         } else {
+          const patchPath = patch.sourceToPatchPath(sourcePath);
           patch$1.push({
             op: "add",
-            path: patch.sourceToPatchPath(sourcePath).concat("metadata"),
-            value: {
-              width: imageMetadata.width,
-              height: imageMetadata.height,
-              mimeType: imageMetadata.mimeType
-            }
+            path: patchPath.concat("width"),
+            value: imageMetadata.width
+          }, {
+            op: "add",
+            path: patchPath.concat("height"),
+            value: imageMetadata.height
+          }, {
+            op: "add",
+            path: patchPath.concat("mimeType"),
+            value: imageMetadata.mimeType
           });
         }
       }
@@ -9465,53 +10194,32 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
           fixes: undefined
         });
       } else if (fix === "file:check-metadata") {
-        const currentValue = validationError.value;
-        const metadataIsCorrect =
-        // metadata is a prop that is an object
-        typeof currentValue === "object" && currentValue && "metadata" in currentValue && currentValue.metadata && typeof currentValue.metadata === "object" &&
-        // mimeType is correct
-        "mimeType" in currentValue.metadata && currentValue.metadata.mimeType === fileMetadata.mimeType;
-
-        // skips if the metadata is already correct
-        if (!metadataIsCorrect) {
+        const currentValue = mediaValueOf(validationError.value);
+        if ((currentValue === null || currentValue === void 0 ? void 0 : currentValue.mimeType) !== fileMetadata.mimeType) {
           if (apply) {
             patch$1.push({
-              op: "replace",
-              path: patch.sourceToPatchPath(sourcePath).concat("metadata"),
-              value: {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                ...currentValue.metadata,
-                ...(fileMetadata.mimeType ? {
-                  mimeType: fileMetadata.mimeType
-                } : {})
-              }
+              op: "add",
+              path: patch.sourceToPatchPath(sourcePath).concat("mimeType"),
+              value: fileMetadata.mimeType ?? null
+            });
+          } else if (currentValue) {
+            remainingErrors.push({
+              message: "File mimeType is incorrect! Found: " + (currentValue.mimeType ?? "<empty>") + ". Expected: " + fileMetadata.mimeType,
+              fixes: undefined
             });
           } else {
-            if (typeof currentValue === "object" && currentValue && "metadata" in currentValue && currentValue.metadata && typeof currentValue.metadata === "object") {
-              if (!("mimeType" in currentValue.metadata) || currentValue.metadata.mimeType !== fileMetadata.mimeType) {
-                remainingErrors.push({
-                  message: "File metadata mimeType is incorrect! Found: " + ("mimeType" in currentValue.metadata ? currentValue.metadata.mimeType : "<empty>") + ". Expected: " + fileMetadata.mimeType,
-                  fixes: undefined
-                });
-              }
-            } else {
-              remainingErrors.push({
-                ...validationError,
-                message: "Image metadata is not an object!",
-                fixes: undefined
-              });
-            }
+            remainingErrors.push({
+              ...validationError,
+              message: "File is not an object!",
+              fixes: undefined
+            });
           }
         }
       } else if (fix === "file:add-metadata") {
         patch$1.push({
           op: "add",
-          path: patch.sourceToPatchPath(sourcePath).concat("metadata"),
-          value: {
-            ...(fileMetadata.mimeType ? {
-              mimeType: fileMetadata.mimeType
-            } : {})
-          }
+          path: patch.sourceToPatchPath(sourcePath).concat("mimeType"),
+          value: fileMetadata.mimeType ?? null
         });
       }
     } else if (fix === "image:upload-remote" || fix === "file:upload-remote") {
@@ -9539,11 +10247,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
       } else {
         patch$1.push({
           op: "replace",
-          value: {
-            _type: "remote",
-            _ref: remoteFile.ref,
-            metadata
-          },
+          value: mediaValue(remoteFile.ref, metadata),
           path: patch.sourceToPatchPath(sourcePath)
         });
       }
@@ -9612,7 +10316,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         });
         continue;
       }
-      const splitRemoteRefDataRes = core.Internal.remote.splitRemoteRef(v._ref);
+      const splitRemoteRefDataRes = core.Internal.remote.splitRemoteRef(v.path);
       if (splitRemoteRefDataRes.status === "error") {
         remainingErrors.push({
           ...validationError,
@@ -9621,7 +10325,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         });
         continue;
       }
-      const url = v._ref;
+      const url = v.path;
       const filePath = splitRemoteRefDataRes.filePath;
       if (!filePath) {
         remainingErrors.push({
@@ -9652,20 +10356,10 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         });
         continue;
       }
-      const value = {
-        [core.VAL_EXTENSION]: "file",
-        [core.FILE_REF_PROP]: `/${filePath}`,
-        ...(fix === "image:download-remote" ? {
-          [core.FILE_REF_SUBTYPE_TAG]: "image"
-        } : {})
-      };
       patch$1.push({
         op: "replace",
         path: patch.sourceToPatchPath(sourcePath),
-        value: v.metadata ? {
-          ...value,
-          metadata: v.metadata
-        } : value
+        value: mediaValue(`/${filePath}`, v.metadata)
       });
     } else if (fix === "images:check-all-files" || fix === "files:check-all-files") {
       if (!moduleSource || typeof moduleSource !== "object") {
@@ -9788,7 +10482,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         schema: schemaAtPath
       } = core.Internal.resolvePath(modulePath, moduleSource, moduleSchema);
       if (schemaAtPath.type === "image" || schemaAtPath.type === "file") {
-        const res = await checkRemoteRef(config.remoteHost, v._ref, config.projectRoot, schemaAtPath, v.metadata);
+        const res = await checkRemoteRef(config.remoteHost, v.path, config.projectRoot, schemaAtPath, v.metadata);
         if (res.status === "success") ; else if (res.status === "error") {
           remainingErrors.push({
             ...validationError,
@@ -9800,11 +10494,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
             patch$1.push({
               op: "replace",
               path: patch.sourceToPatchPath(sourcePath),
-              value: {
-                _type: "remote",
-                _ref: res.ref,
-                metadata: res.metadata
-              }
+              value: mediaValue(res.ref, res.metadata)
             });
           } else {
             remainingErrors.push({
@@ -9830,80 +10520,695 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
       }
     }
   }
-  if (!validationError.fixes || validationError.fixes.length === 0) {
-    remainingErrors.push(validationError);
+  if (!validationError.fixes || validationError.fixes.length === 0) {
+    remainingErrors.push(validationError);
+  }
+  return {
+    patch: patch$1,
+    remainingErrors
+  };
+}
+function getRemoteValueFromValidationError(v) {
+  if (v.value && typeof v.value !== "object") {
+    return {
+      success: false,
+      message: "Unexpected error while checking remote (not an object)"
+    };
+  }
+  if (!v.value) {
+    return {
+      success: false,
+      message: "Unexpected error while checking remote (no value)"
+    };
+  }
+  if (typeof v.value !== "object" || v.value === null || !("path" in v.value)) {
+    return {
+      success: false,
+      message: "Unexpected error while checking remote (no path in value)"
+    };
+  }
+  if (typeof v.value.path !== "string") {
+    return {
+      success: false,
+      message: "Unexpected error while checking remote (path is not a string)"
+    };
+  }
+  // Everything but the path is what Val read from the bytes.
+  const {
+    path,
+    ...metadata
+  } = v.value;
+  return {
+    success: true,
+    path,
+    metadata
+  };
+}
+async function getImageMetadata(projectRoot, validationError) {
+  const fileRef = getValidationErrorFileRef(validationError);
+  if (!fileRef) {
+    // TODO:
+    throw Error("Cannot fix image without a file reference");
+  }
+  const filename = path__namespace["default"].join(projectRoot, fileRef);
+  const buffer = fs__default["default"].readFileSync(filename);
+  return extractImageMetadata(filename, buffer);
+}
+async function getFileMetadata(projectRoot, validationError) {
+  const fileRef = getValidationErrorFileRef(validationError);
+  if (!fileRef) {
+    // TODO:
+    throw Error("Cannot fix file without a file reference");
+  }
+  const filename = path__namespace["default"].join(projectRoot, fileRef);
+  fs__default["default"].readFileSync(filename);
+  return extractFileMetadata(fileRef);
+}
+
+/**
+ * Moves ONE `.jsonValues()` entry that was written inline in the `.val.ts` into
+ * its own `*.val.json`, replacing the inline value with
+ * `c.json(() => import("./<key>.val.json"))`.
+ *
+ * This is the fix for the `jsonValues:extract-entry` validation error. It is not
+ * expressible as a patch (a patch edits one `.val.ts` and cannot create the
+ * backing JSON file), so it writes both files directly — JSON first, so a
+ * failure part-way through never leaves the module pointing at a file that does
+ * not exist.
+ *
+ * Root-only, like the rest of the `.jsonValues()` machinery: the entry is looked
+ * up in the module's root record/router object literal.
+ */
+function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sourceFileHandler) {
+  const valTsPath = sourceFileHandler.resolveSourceModulePath(getSyntheticContainingPath(rootDir), `.${moduleFilePath.replace(".val.ts", ".val").replace(".val.js", ".val").replace(".val.jsx", ".val").replace(".val.tsx", ".val")}`);
+  const sourceFile = sourceFileHandler.getSourceFile(valTsPath);
+  if (!sourceFile) {
+    throw Error(`Source file ${valTsPath} not found`);
+  }
+  const pathsRes = getNewJsonEntryPaths(moduleFilePath, entryKey);
+  if (fp.result.isErr(pathsRes)) {
+    throw Error(formatPatchSourceError(pathsRes.error));
+  }
+  const {
+    jsonPath,
+    importPath
+  } = pathsRes.value;
+  const absoluteJsonPath = path__namespace["default"].join(rootDir, jsonPath);
+  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
+    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${jsonPath}' already exists`);
+  }
+
+  // Remove the inline property, then add the `c.json(...)` reference back. The
+  // entry moves to the end of the record: entry ORDER in a jsonValues record is
+  // not meaningful (the Studio and the runtime key entries by name), and
+  // insert-in-place would mean reimplementing insertValJsonEntry.
+  const removed = removeValJsonEntry(sourceFile, [], entryKey);
+  if (fp.result.isErr(removed)) {
+    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
+  }
+  const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
+  if (fp.result.isErr(inserted)) {
+    throw Error(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+  }
+  sourceFileHandler.writeFile(absoluteJsonPath, JSON.stringify(content, null, 2) + "\n", "utf8");
+  sourceFileHandler.writeSourceFile(inserted.value);
+}
+function formatOpsError(error, sourceFile) {
+  if (error instanceof patch.PatchError) {
+    return error.message;
+  }
+  return flatMapErrors(error, e => formatSyntaxError(e, sourceFile)).join("\n");
+}
+
+/**
+ * The fix handlers behind `val validate --fix`, and the editor quick fixes that
+ * must agree with it.
+ *
+ * ## Why this lives in `@valbuild/server`
+ *
+ * A fix is two layers. `createFixPatch` is the second: given a validation
+ * error it produces a patch. The first is everything that has to happen before a
+ * patch can be produced — read the file, check it is actually on disk, extract
+ * metadata, pick a remote bucket, upload the bytes, download them back. That
+ * layer used to live in `packages/cli/src/runValidation.ts`, which made it
+ * reachable only from the CLI: `@valbuild/cli` exports nothing but `./cli`, and
+ * `@valbuild/language-server` cannot depend on it anyway without creating a
+ * cycle (the CLI depends on the language server).
+ *
+ * The consequence was that an editor could offer the fixes needing no
+ * precondition and had to reimplement or skip the rest. Both happened: the
+ * VS Code extension grew its own remote-upload client, and the language server
+ * declined to offer remote fixes at all.
+ *
+ * So the layer sits here, next to `createFixPatch`, and the CLI and the language
+ * server are both callers. {@link FixHandlerContext} is deliberately made of
+ * things any caller already has — a `Service`, an `IValFSHost`, a project root —
+ * rather than of CLI concepts.
+ *
+ * What stays in the CLI is the driver: the `runValidation` async generator that
+ * walks every module, decides what to report, and renders it to a terminal.
+ */
+const textEncoder = new TextEncoder();
+
+// Types for handler system
+
+// Handler functions
+async function handleFileMetadata(ctx) {
+  var _fileSource$source;
+  const [, modulePath] = core.Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  if (!ctx.valModule.source || !ctx.valModule.schema) {
+    return {
+      success: false,
+      errorMessage: `Could not resolve source or schema for ${ctx.sourcePath}`
+    };
+  }
+  const fileSource = core.Internal.resolvePath(modulePath, ctx.valModule.source, ctx.valModule.schema);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const fileRefProp = (_fileSource$source = fileSource.source) === null || _fileSource$source === void 0 ? void 0 : _fileSource$source.path;
+  if (!fileRefProp) {
+    return {
+      success: false,
+      errorMessage: `Expected file to be defined at: ${ctx.sourcePath} but no file was found`
+    };
+  }
+  const filePath = path__namespace["default"].join(ctx.projectRoot, fileRefProp);
+  if (!ctx.fs.fileExists(filePath)) {
+    return {
+      success: false,
+      errorMessage: `File ${filePath} does not exist`
+    };
+  }
+  return {
+    success: true,
+    shouldApplyPatch: true
+  };
+}
+
+// Shared upload core used by both the single-field (handleRemoteFileUpload)
+// and gallery (handleRemoteGalleryFileUpload) handlers. The two differ only in
+// how they derive the local file ref, metadata and serialized image/file
+// schema; everything from auth through upload is identical.
+async function uploadRemoteFileCore(ctx, fileRef, metadata, schema) {
+  const filePath = path__namespace["default"].join(ctx.projectRoot, fileRef);
+  if (!ctx.fs.fileExists(filePath)) {
+    return {
+      success: false,
+      errorMessage: `File ${filePath} does not exist`
+    };
+  }
+  const patFile = getPersonalAccessTokenPath(ctx.projectRoot);
+  if (!ctx.fs.fileExists(patFile)) {
+    return {
+      success: false,
+      errorMessage: `File: ${path__namespace["default"].join(ctx.projectRoot, ctx.file)} has remote images that are not uploaded and you are not logged in.\n\nFix this error by logging in:\n\t"npx val login"\n`
+    };
+  }
+  const patFileContent = ctx.fs.readFile(patFile);
+  if (patFileContent === undefined) {
+    return {
+      success: false,
+      errorMessage: `Could not read personal access token file at ${patFile}`
+    };
+  }
+  const parsedPatFile = parsePersonalAccessTokenFile(patFileContent);
+  if (!parsedPatFile.success) {
+    return {
+      success: false,
+      errorMessage: `Error parsing personal access token file: ${parsedPatFile.error}. You need to login again.`
+    };
+  }
+  const {
+    pat
+  } = parsedPatFile.data;
+  if (ctx.remoteFiles[ctx.sourcePath]) {
+    return {
+      success: true,
+      events: [{
+        type: "remote-already-uploaded",
+        filePath
+      }]
+    };
+  }
+  const projectName = ctx.project;
+  let publicProjectId = ctx.publicProjectId;
+  let remoteFileBuckets = ctx.remoteFileBuckets;
+  let remoteFilesCounter = ctx.remoteFilesCounter;
+  if (!publicProjectId || !remoteFileBuckets) {
+    if (!projectName) {
+      return {
+        success: false,
+        errorMessage: "Project name not found. Add project name to val.config or set the VAL_PROJECT environment variable"
+      };
+    }
+    const settingsRes = await ctx.remote.getSettings(projectName, {
+      pat
+    });
+    if (!settingsRes.success) {
+      return {
+        success: false,
+        errorMessage: `Could not get public project id: ${settingsRes.message}.`
+      };
+    }
+    publicProjectId = settingsRes.data.publicProjectId;
+    remoteFileBuckets = settingsRes.data.remoteFileBuckets.map(b => b.bucket);
+  }
+  if (!publicProjectId) {
+    return {
+      success: false,
+      errorMessage: "Could not get public project id"
+    };
+  }
+  if (!projectName) {
+    return {
+      success: false,
+      errorMessage: `Could not get project. Check that your val.config has the 'project' field set, or set it using the VAL_PROJECT environment variable`
+    };
+  }
+  remoteFilesCounter += 1;
+  const bucket = remoteFileBuckets[remoteFilesCounter % remoteFileBuckets.length];
+  if (!bucket) {
+    return {
+      success: false,
+      errorMessage: `Internal error: could not allocate a bucket for the remote file located at ${ctx.sourcePath}`
+    };
+  }
+  const fileBuffer = ctx.fs.readBuffer(filePath);
+  if (fileBuffer === undefined) {
+    return {
+      success: false,
+      errorMessage: `Error reading file: ${filePath}`
+    };
+  }
+  const relativeFilePath = path__namespace["default"].relative(ctx.projectRoot, filePath).split(path__namespace["default"].sep).join("/");
+  if (!relativeFilePath.startsWith("public/")) {
+    return {
+      success: false,
+      errorMessage: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
+    };
+  }
+  const fileHash = core.Internal.remote.getFileHash(fileBuffer);
+  const coreVersion = core.Internal.VERSION.core || "unknown";
+  const fileExt = getFileExt(filePath);
+  const ref = core.Internal.remote.createRemoteRef(ctx.remote.remoteHost, {
+    publicProjectId,
+    coreVersion,
+    bucket,
+    validationHash: core.Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata, fileHash, textEncoder),
+    fileHash,
+    filePath: relativeFilePath
+  });
+  const remoteFileUpload = await ctx.remote.uploadFile(projectName, bucket, fileHash, fileExt, fileBuffer, {
+    pat
+  });
+  if (!remoteFileUpload.success) {
+    return {
+      success: false,
+      errorMessage: `Could not upload remote file: '${ref}'. Error: ${remoteFileUpload.error}`
+    };
   }
+  ctx.remoteFiles[ctx.sourcePath] = {
+    ref,
+    metadata
+  };
   return {
-    patch: patch$1,
-    remainingErrors
+    success: true,
+    shouldApplyPatch: true,
+    publicProjectId,
+    remoteFileBuckets,
+    remoteFilesCounter,
+    events: [{
+      type: "remote-uploading",
+      ref
+    }, {
+      type: "remote-uploaded",
+      ref
+    }]
   };
 }
-function getRemoteValueFromValidationError(v) {
-  if (v.value && typeof v.value !== "object") {
+async function handleRemoteFileUpload(ctx) {
+  var _resolvedRemoteFileAt;
+  if (!ctx.fix) {
     return {
       success: false,
-      message: "Unexpected error while checking remote (not an object)"
+      // No sourcePath in the message: the reported location already points at it.
+      errorMessage: `Remote file needs to be uploaded (use --fix to upload)`
     };
   }
-  if (!v.value) {
+  const [, modulePath] = core.Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  if (!ctx.valModule.source || !ctx.valModule.schema) {
     return {
       success: false,
-      message: "Unexpected error while checking remote (no value)"
+      errorMessage: `Could not resolve source or schema for ${ctx.sourcePath}`
     };
   }
-  if (typeof v.value !== "object" || v.value === null || !(core.FILE_REF_PROP in v.value)) {
+  const resolvedRemoteFileAtSourcePath = core.Internal.resolvePath(modulePath, ctx.valModule.source, ctx.valModule.schema);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const fileRefProp = (_resolvedRemoteFileAt = resolvedRemoteFileAtSourcePath.source) === null || _resolvedRemoteFileAt === void 0 ? void 0 : _resolvedRemoteFileAt.path;
+  if (!fileRefProp) {
     return {
       success: false,
-      message: "Unexpected error while checking remote (no _ref in value)"
+      errorMessage: `Expected file to be defined at: ${ctx.sourcePath} but no file was found`
     };
   }
-  if (typeof v.value._ref !== "string") {
+  const resolveRemoteFileSchema = resolvedRemoteFileAtSourcePath.schema;
+  if (!resolveRemoteFileSchema) {
     return {
       success: false,
-      message: "Unexpected error while checking remote (_ref is not a string)"
+      errorMessage: `Cannot upload remote file: schema not found for ${ctx.sourcePath}`
     };
   }
-  let metadata;
-  if ("metadata" in v.value && typeof v.value.metadata === "object") {
-    if (v.value.metadata === null) {
-      return {
-        success: false,
-        message: "Unexpected error while checking remote (metadata is null)"
-      };
+  if (resolveRemoteFileSchema.type !== "image" && resolveRemoteFileSchema.type !== "file") {
+    return {
+      success: false,
+      errorMessage: `The schema is the remote is neither image nor file: ${ctx.sourcePath}`
+    };
+  }
+
+  // The metadata is everything the media source carries besides its path: the
+  // schema above already established that this IS media.
+  const actualRemoteFileSource = resolvedRemoteFileAtSourcePath.source;
+  const fileSourceMetadata = actualRemoteFileSource && typeof actualRemoteFileSource === "object" && "path" in actualRemoteFileSource ? (() => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const {
+      path: _path,
+      ...metadata
+    } = actualRemoteFileSource;
+    return metadata;
+  })() : undefined;
+  return uploadRemoteFileCore(ctx, fileRefProp, fileSourceMetadata, resolveRemoteFileSchema);
+}
+
+// Gallery (s.images({ remote: true }) / s.files({ remote: true })) upload.
+// Unlike a single image/file field, a gallery entry is keyed by its local file
+// path and the value is bare metadata (no FileSource), so we derive the file
+// ref from the key and synthesize the image/file schema from the record's
+// media options.
+async function handleRemoteGalleryFileUpload(ctx) {
+  var _ctx$validationError$;
+  if (!ctx.fix) {
+    return {
+      success: false,
+      // No sourcePath in the message: the reported location already points at it.
+      errorMessage: `Remote file needs to be uploaded (use --fix to upload)`
+    };
+  }
+  const fix = (_ctx$validationError$ = ctx.validationError.fixes) === null || _ctx$validationError$ === void 0 ? void 0 : _ctx$validationError$[0];
+  const mediaType = fix === "files:upload-remote" ? "file" : "image";
+
+  // The gallery entry is keyed by its local file path; validateMediaKey carries
+  // that key as the error value.
+  const fileRef = ctx.validationError.value;
+  if (typeof fileRef !== "string") {
+    return {
+      success: false,
+      errorMessage: `Expected a local file path for gallery entry at ${ctx.sourcePath}`
+    };
+  }
+  const [, modulePath] = core.Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  if (!ctx.valModule.source || !ctx.valModule.schema) {
+    return {
+      success: false,
+      errorMessage: `Could not resolve source or schema for ${ctx.sourcePath}`
+    };
+  }
+  const resolved = core.Internal.resolvePath(modulePath, ctx.valModule.source, ctx.valModule.schema);
+  const entrySource = resolved.source;
+  const metadata = entrySource && typeof entrySource === "object" && !Array.isArray(entrySource) ? entrySource : undefined;
+
+  // The gallery item schema is an ObjectSchema, not an image/file schema, so
+  // synthesize the serialized image/file schema (matching how single fields
+  // serialize) for the remote ref's validation hash.
+  //
+  // `accept`/`directory` come from the RECORD that holds the entry, resolved
+  // from the entry's PARENT path - not from the module root, which is only the
+  // record when the gallery is the whole module. A nested gallery
+  // (s.object({ gallery: s.images(...) })) would otherwise synthesize a schema
+  // with no options and bake a validation hash into the remote ref that can
+  // never validate, so a mismatch fails fast instead of uploading.
+  const [, parentModulePath] = core.Internal.splitModuleFilePathAndModulePath(core.Internal.parentOfSourcePath(ctx.sourcePath));
+  const recordSchema = core.Internal.resolvePath(parentModulePath, ctx.valModule.source, ctx.valModule.schema).schema;
+  if ((recordSchema === null || recordSchema === void 0 ? void 0 : recordSchema.type) !== "record") {
+    return {
+      success: false,
+      errorMessage: `Expected a gallery record at the parent of ${ctx.sourcePath}, got ${(recordSchema === null || recordSchema === void 0 ? void 0 : recordSchema.type) ?? "nothing"}`
+    };
+  }
+  const {
+    accept,
+    directory
+  } = recordSchema;
+  const schema = mediaType === "image" ? {
+    type: "image",
+    opt: false,
+    options: {
+      ...(accept ? {
+        accept
+      } : {}),
+      ...(directory ? {
+        directory
+      } : {})
+    }
+  } : {
+    type: "file",
+    opt: false,
+    options: {
+      ...(accept ? {
+        accept
+      } : {})
+    }
+  };
+  return uploadRemoteFileCore(ctx, fileRef, metadata, schema);
+}
+async function handleRemoteFileDownload(ctx) {
+  if (ctx.fix) {
+    return {
+      success: true,
+      shouldApplyPatch: true,
+      events: [{
+        type: "remote-downloading",
+        sourcePath: ctx.sourcePath
+      }]
+    };
+  } else {
+    return {
+      success: false,
+      errorMessage: `Remote file ${ctx.sourcePath} needs to be downloaded (use --fix to download)`
+    };
+  }
+}
+async function handleRemoteFileCheck() {
+  // Skip - no action needed
+  return {
+    success: true,
+    shouldApplyPatch: true
+  };
+}
+async function handleUniqueFolderCheck(ctx) {
+  const value = ctx.validationError.value;
+  if (!value || typeof value.directory !== "string") {
+    return {
+      success: false,
+      errorMessage: `Unexpected value in unique folder check for ${ctx.sourcePath}`
+    };
+  }
+  const {
+    directory
+  } = value;
+  const conflicts = [];
+  for (const file of ctx.valFiles) {
+    const otherModuleFilePath = `/${file}`;
+    if (otherModuleFilePath === ctx.moduleFilePath) continue;
+    const otherModule = await ctx.service.get(otherModuleFilePath, "", {
+      validate: false
+    });
+    const schema = otherModule.schema;
+    if ((schema === null || schema === void 0 ? void 0 : schema.type) === "record" && schema.directory === directory && schema.mediaType) {
+      conflicts.push(otherModuleFilePath);
     }
-    if (Array.isArray(v.value.metadata)) {
+  }
+  if (conflicts.length > 0) {
+    return {
+      success: false,
+      errorMessage: `Gallery directory '${directory}' in ${ctx.moduleFilePath} is also used by: ${conflicts.join(", ")}. Each gallery must use a unique directory.`
+    };
+  }
+  return {
+    success: true
+  };
+}
+
+// Maps a gallery key to its on-disk local path. Remote galleries key uploaded
+// entries by a remote URL while keeping the file on disk; everything else is
+// already a local path and is returned unchanged.
+function remoteKeyToLocalPath(key) {
+  const remoteRefRes = core.Internal.remote.splitRemoteRef(key);
+  if (remoteRefRes.status === "success") {
+    return `/${remoteRefRes.filePath}`;
+  }
+  return key;
+}
+async function handleCheckAllFiles(ctx) {
+  const value = ctx.validationError.value;
+  if (!value || typeof value.directory !== "string") {
+    return {
+      success: false,
+      errorMessage: `Unexpected value in check-all-files for ${ctx.sourcePath}`
+    };
+  }
+  const {
+    directory
+  } = value;
+  const source = ctx.valModule.source;
+  if (!source || typeof source !== "object" || Array.isArray(source)) {
+    return {
+      success: false,
+      errorMessage: `Could not get source for ${ctx.sourcePath}`
+    };
+  }
+  // Gallery entries are keyed by their file path. Remote galleries key uploaded
+  // entries by a remote URL, but the file is kept on disk at its local path, so
+  // normalize remote-URL keys back to that local path for the on-disk checks.
+  const trackedFiles = new Set(Object.keys(source).map(remoteKeyToLocalPath));
+
+  // Check that all tracked files exist on disk
+  const missingTrackedFiles = Array.from(trackedFiles).filter(f => {
+    return !ctx.fs.fileExists(path__namespace["default"].join(ctx.projectRoot, f));
+  });
+  if (missingTrackedFiles.length > 0) {
+    if (!ctx.fix) {
       return {
         success: false,
-        message: "Unexpected error while checking remote (metadata is an array)"
+        errorMessage: `Gallery in ${ctx.moduleFilePath} has tracked files that do not exist on disk: ${missingTrackedFiles.join(", ")}. Add the files or remove them from the gallery.`
       };
     }
-    metadata = v.value.metadata;
+    // fix: true — let createFixPatch remove the missing entries
+    return {
+      success: true,
+      shouldApplyPatch: true
+    };
+  }
+  const dirPath = path__namespace["default"].join(ctx.projectRoot, directory);
+  const filesInDir = [];
+  try {
+    const entries = ctx.fs.readDirectory(dirPath, undefined, undefined, ["**/*"]);
+    for (const entry of entries) {
+      const relPath = "/" + path__namespace["default"].relative(ctx.projectRoot, entry).split(path__namespace["default"].sep).join("/");
+      filesInDir.push(relPath);
+    }
+  } catch {
+    // directory doesn't exist — no untracked files possible
+  }
+  const untrackedFiles = filesInDir.filter(f => !trackedFiles.has(f));
+  if (untrackedFiles.length > 0) {
+    return {
+      success: false,
+      errorMessage: `Gallery in ${ctx.moduleFilePath} has files not tracked: ${untrackedFiles.join(", ")}. Add these files to the gallery or remove them from the directory.`
+    };
   }
+
+  // All files accounted for — trigger metadata verification via createFixPatch
   return {
     success: true,
-    _ref: v.value._ref,
-    metadata
+    shouldApplyPatch: true
   };
 }
-async function getImageMetadata(projectRoot, validationError) {
-  const fileRef = getValidationErrorFileRef(validationError);
-  if (!fileRef) {
-    // TODO:
-    throw Error("Cannot fix image without a file reference");
+async function handleJsonValuesExtractEntry(ctx) {
+  const [, modulePath] = core.Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  const parts = core.Internal.splitModulePath(modulePath);
+  // Root-only by contract (see findNestedJsonValuesRecords): the entry is a
+  // direct child of the module's root record/router, so the path is one segment.
+  if (parts.length !== 1) {
+    return {
+      success: false,
+      errorMessage: `Cannot extract .jsonValues() entry at ${ctx.sourcePath}: expected a root record entry`
+    };
   }
-  const filename = path__namespace["default"].join(projectRoot, fileRef);
-  const buffer = fs__default["default"].readFileSync(filename);
-  return extractImageMetadata(filename, buffer);
-}
-async function getFileMetadata(projectRoot, validationError) {
-  const fileRef = getValidationErrorFileRef(validationError);
-  if (!fileRef) {
-    // TODO:
-    throw Error("Cannot fix file without a file reference");
+  const entryKey = parts[0];
+  const source = ctx.valModule.source;
+  if (source === null || typeof source !== "object" || Array.isArray(source)) {
+    return {
+      success: false,
+      errorMessage: `Could not get source for ${ctx.moduleFilePath}`
+    };
   }
-  const filename = path__namespace["default"].join(projectRoot, fileRef);
-  fs__default["default"].readFileSync(filename);
-  return extractFileMetadata(fileRef);
+  const content = source[entryKey];
+  if (content === undefined) {
+    return {
+      success: false,
+      errorMessage: `Could not find .jsonValues() entry '${entryKey}' in ${ctx.moduleFilePath}`
+    };
+  }
+  if (!ctx.fix) {
+    return {
+      success: true,
+      fixableErrorMessage: ctx.validationError.message
+    };
+  }
+  try {
+    extractJsonValuesEntry(ctx.moduleFilePath, ctx.projectRoot, entryKey, content, ctx.service.sourceFileHandler);
+  } catch (err) {
+    return {
+      success: false,
+      errorMessage: err instanceof Error ? err.message : String(err)
+    };
+  }
+  return {
+    success: true,
+    appliedFix: true
+  };
+}
+
+// Fix handler registry. `keyof:check-keys` and `router:check-route` are
+// resolved upfront by the shared resolveSchemaSourceFixes — they never reach
+// this registry, so they're excluded from the key set.
+const currentFixHandlers = {
+  "image:check-metadata": handleFileMetadata,
+  "image:add-metadata": handleFileMetadata,
+  "file:check-metadata": handleFileMetadata,
+  "file:add-metadata": handleFileMetadata,
+  "image:upload-remote": handleRemoteFileUpload,
+  "file:upload-remote": handleRemoteFileUpload,
+  "images:upload-remote": handleRemoteGalleryFileUpload,
+  "files:upload-remote": handleRemoteGalleryFileUpload,
+  "image:download-remote": handleRemoteFileDownload,
+  "file:download-remote": handleRemoteFileDownload,
+  "image:check-remote": handleRemoteFileCheck,
+  "images:check-remote": handleRemoteFileCheck,
+  "file:check-remote": handleRemoteFileCheck,
+  "files:check-remote": handleRemoteFileCheck,
+  "images:check-unique-folder": handleUniqueFolderCheck,
+  "files:check-unique-folder": handleUniqueFolderCheck,
+  "images:check-all-files": handleCheckAllFiles,
+  "files:check-all-files": handleCheckAllFiles,
+  "jsonValues:extract-entry": handleJsonValuesExtractEntry
+};
+const deprecatedFixHandlers = {
+  "image:replace-metadata": handleFileMetadata
+};
+const fixHandlers = {
+  ...deprecatedFixHandlers,
+  ...currentFixHandlers
+};
+function createDefaultValFSHost() {
+  return {
+    ...ts__default["default"].sys,
+    writeFile: (fileName, data, encoding) => {
+      fs__default["default"].mkdirSync(path__namespace["default"].dirname(fileName), {
+        recursive: true
+      });
+      fs__default["default"].writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
+    },
+    rmFile: fs__default["default"].rmSync,
+    readBuffer: fileName => {
+      try {
+        return fs__default["default"].readFileSync(fileName);
+      } catch {
+        return undefined;
+      }
+    }
+  };
 }
 
 function validateMetadata(actualMetadata, expectedMetadata) {
@@ -10198,9 +11503,9 @@ function getModulePathRange(modulePath, modulePathMap,
 // Which part of an object/record member to point at. For an object property
 // the resolved node's own range is the *key* (property name); the *value*
 // range is stored under `children.val`. Array elements, leaf literals and
-// `c.image`/`c.file` `_ref`/`metadata` nodes have no `val` child, so "value"
-// falls back to the node's own range for those. Defaults to "key" to preserve
-// existing callers.
+// Array elements and leaf literals have no `val` child, so "value" falls back
+// to the node's own range for those. Defaults to "key" to preserve existing
+// callers.
 target = "key") {
   var _range$children;
   // Handle invalid module paths gracefully
@@ -10253,7 +11558,7 @@ target = "key") {
  *
  * NOTE: do not compute the start as `end.character - node.getWidth()`. That
  * identity only holds while the node stays on a single line - for a multi-line
- * node (an object inside an array, a `c.image` metadata argument, ...) it
+ * node (an object inside an array, a media object's `path`, ...) it
  * reports the *closing* line and a negative character.
  */
 function rangeOf(node, sourceFile) {
@@ -10317,39 +11622,6 @@ function traverse(node, sourceFile) {
   if (ts__default["default"].isArrayLiteralExpression(node)) {
     return traverseArrayLiteral(node, sourceFile);
   }
-  if (ts__default["default"].isCallExpression(node)) {
-    return traverseCallExpression(node, sourceFile);
-  }
-}
-function traverseCallExpression(node, sourceFile) {
-  if (ts__default["default"].isPropertyAccessExpression(node.expression)) {
-    if (node.expression.expression.getText(sourceFile) === "c" && (node.expression.name.getText(sourceFile) === "file" || node.expression.name.getText(sourceFile) === "image")) {
-      const val = {
-        children: {},
-        ...rangeOf(node, sourceFile)
-      };
-      if (node.arguments[0]) {
-        const _ref = {
-          children: {},
-          ...rangeOf(node.arguments[0], sourceFile)
-        };
-        if (!node.arguments[1]) {
-          return {
-            val,
-            _ref
-          };
-        }
-        return {
-          val,
-          _ref,
-          metadata: {
-            children: {},
-            ...rangeOf(node.arguments[1], sourceFile)
-          }
-        };
-      }
-    }
-  }
 }
 function traverseArrayLiteral(node, sourceFile) {
   return node.elements.reduce((acc, element, index) => {
@@ -10423,61 +11695,6 @@ function findJsonEntryFilePath(moduleFilePath, valTsSourceFile, entryKey) {
   return resolveExistingJsonPath(moduleFilePath, entry.importPath);
 }
 
-/**
- * Moves ONE `.jsonValues()` entry that was written inline in the `.val.ts` into
- * its own `*.val.json`, replacing the inline value with
- * `c.json(() => import("./<key>.val.json"))`.
- *
- * This is the fix for the `jsonValues:extract-entry` validation error. It is not
- * expressible as a patch (a patch edits one `.val.ts` and cannot create the
- * backing JSON file), so it writes both files directly — JSON first, so a
- * failure part-way through never leaves the module pointing at a file that does
- * not exist.
- *
- * Root-only, like the rest of the `.jsonValues()` machinery: the entry is looked
- * up in the module's root record/router object literal.
- */
-function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sourceFileHandler) {
-  const valTsPath = sourceFileHandler.resolveSourceModulePath(getSyntheticContainingPath(rootDir), `.${moduleFilePath.replace(".val.ts", ".val").replace(".val.js", ".val").replace(".val.jsx", ".val").replace(".val.tsx", ".val")}`);
-  const sourceFile = sourceFileHandler.getSourceFile(valTsPath);
-  if (!sourceFile) {
-    throw Error(`Source file ${valTsPath} not found`);
-  }
-  const pathsRes = getNewJsonEntryPaths(moduleFilePath, entryKey);
-  if (fp.result.isErr(pathsRes)) {
-    throw Error(formatPatchSourceError(pathsRes.error));
-  }
-  const {
-    jsonPath,
-    importPath
-  } = pathsRes.value;
-  const absoluteJsonPath = path__namespace["default"].join(rootDir, jsonPath);
-  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
-    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${jsonPath}' already exists`);
-  }
-
-  // Remove the inline property, then add the `c.json(...)` reference back. The
-  // entry moves to the end of the record: entry ORDER in a jsonValues record is
-  // not meaningful (the Studio and the runtime key entries by name), and
-  // insert-in-place would mean reimplementing insertValJsonEntry.
-  const removed = removeValJsonEntry(sourceFile, [], entryKey);
-  if (fp.result.isErr(removed)) {
-    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
-  }
-  const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
-  if (fp.result.isErr(inserted)) {
-    throw Error(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
-  }
-  sourceFileHandler.writeFile(absoluteJsonPath, JSON.stringify(content, null, 2) + "\n", "utf8");
-  sourceFileHandler.writeSourceFile(inserted.value);
-}
-function formatOpsError(error, sourceFile) {
-  if (error instanceof patch.PatchError) {
-    return error.message;
-  }
-  return flatMapErrors(error, e => formatSyntaxError(e, sourceFile)).join("\n");
-}
-
 /**
  * Replays a `val debug` snapshot: applies its patches the way /save does and
  * validates the result.
@@ -10595,13 +11812,16 @@ exports.analyzeValModule = analyzeValModule;
 exports.awaitValLoginConfirmation = awaitValLoginConfirmation;
 exports.checkRemoteRef = checkRemoteRef;
 exports.compareWithCapturedReport = compareWithCapturedReport;
+exports.createDefaultValFSHost = createDefaultValFSHost;
 exports.createFixPatch = createFixPatch;
 exports.createJsonEntryPathMap = createJsonEntryPathMap;
 exports.createModulePathMap = createModulePathMap;
 exports.createService = createService;
 exports.createValApiRouter = createValApiRouter;
 exports.createValServer = createValServer;
+exports.currentFixHandlers = currentFixHandlers;
 exports.decodeJwt = decodeJwt;
+exports.describePatchStoreProblems = describePatchStoreProblems;
 exports.downloadFileFromRemote = downloadFileFromRemote;
 exports.encodeJwt = encodeJwt;
 exports.evalValConfigFile = evalValConfigFile;
@@ -10610,6 +11830,7 @@ exports.extractImageMetadata = extractImageMetadata;
 exports.extractJsonValuesEntry = extractJsonValuesEntry;
 exports.findAndEvalValConfigFile = findAndEvalValConfigFile;
 exports.findJsonEntryFilePath = findJsonEntryFilePath;
+exports.fixHandlers = fixHandlers;
 exports.formatPatchSourceError = formatPatchSourceError;
 exports.formatSyntaxErrorTree = formatSyntaxErrorTree;
 exports.getCachedRemoteFileDir = getCachedRemoteFileDir;
@@ -10621,11 +11842,20 @@ exports.getModulePathRange = getModulePathRange;
 exports.getPersonalAccessTokenPath = getPersonalAccessTokenPath;
 exports.getSettings = getSettings;
 exports.getValidationErrorFileRef = getValidationErrorFileRef;
+exports.handleCheckAllFiles = handleCheckAllFiles;
+exports.handleFileMetadata = handleFileMetadata;
+exports.handleJsonValuesExtractEntry = handleJsonValuesExtractEntry;
+exports.handleRemoteFileCheck = handleRemoteFileCheck;
+exports.handleRemoteFileDownload = handleRemoteFileDownload;
+exports.handleRemoteFileUpload = handleRemoteFileUpload;
+exports.handleRemoteGalleryFileUpload = handleRemoteGalleryFileUpload;
+exports.handleUniqueFolderCheck = handleUniqueFolderCheck;
 exports.loadValModules = loadValModules;
 exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;
 exports.patchSourceFile = patchSourceFile;
 exports.persistPersonalAccessToken = persistPersonalAccessToken;
 exports.readCapturedReport = readCapturedReport;
+exports.readPatchStore = readPatchStore;
 exports.replaySnapshot = replaySnapshot;
 exports.safeReadGit = safeReadGit;
 exports.startValLogin = startValLogin;