@valbuild/server 0.101.1 → 0.103.0

package/dist/valbuild-server.esm.js

@@ -1,7 +1,8 @@
 import ts from 'typescript';
 import { pipe, result, array } from '@valbuild/core/fp';
-import { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG, VAL_EXTENSION, derefPatch, RecordSchema, Internal, extractValModules, ImageSchema, DEFAULT_CONTENT_HOST } from '@valbuild/core';
 import { PatchError, deepEqual, parseAndValidateArrayIndex, isNotRoot, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
+import { derefPatch, RecordSchema, Internal, extractValModules, VAL_EXTENSION, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema } from '@valbuild/core';
+export { hasRemoteFileSchema } from '@valbuild/core';
 import * as path from 'path';
 import path__default from 'path';
 import fs, { promises } from 'fs';
@@ -68,7 +69,7 @@ function validateObjectProperties(nodes) {
  * validating its children.
  */
 function shallowValidateExpression(value) {
-  return ts.isStringLiteralLike(value) || ts.isNumericLiteral(value) || value.kind === ts.SyntaxKind.TrueKeyword || value.kind === ts.SyntaxKind.FalseKeyword || value.kind === ts.SyntaxKind.NullKeyword || ts.isArrayLiteralExpression(value) || ts.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.isStringLiteralLike(value) || ts.isNumericLiteral(value) || value.kind === ts.SyntaxKind.TrueKeyword || value.kind === ts.SyntaxKind.FalseKeyword || value.kind === ts.SyntaxKind.NullKeyword || ts.isArrayLiteralExpression(value) || ts.isObjectLiteralExpression(value) ? undefined : new ValSyntaxError("Expression must be a literal", value);
 }
 
 /**
@@ -94,55 +95,8 @@ function evaluateExpression(value) {
     return result.all(value.elements.map(evaluateExpression));
   } else if (ts.isObjectLiteralExpression(value)) {
     return pipe(validateObjectProperties(value.properties), result.flatMap(assignments => pipe(assignments.map(assignment => pipe(evaluateExpression(assignment.initializer), result.map(value => [assignment.name.text, value]))), result.all)), result.map(Object.fromEntries));
-  } else if (isValFileMethodCall(value)) {
-    return pipe(findValFileNodeArg(value), result.flatMap(ref => {
-      if (value.arguments.length === 2) {
-        return pipe(evaluateExpression(value.arguments[1]), result.map(metadata => ({
-          [FILE_REF_PROP]: ref.text,
-          _type: "file",
-          metadata
-        })));
-      } else {
-        return result.ok({
-          [FILE_REF_PROP]: ref.text,
-          _type: "file"
-        });
-      }
-    }));
-  } else if (isValImageMethodCall(value)) {
-    return pipe(findValImageNodeArg(value), result.flatMap(ref => {
-      if (value.arguments.length === 2) {
-        return pipe(evaluateExpression(value.arguments[1]), result.map(metadata => ({
-          [FILE_REF_PROP]: ref.text,
-          _type: "file",
-          [FILE_REF_SUBTYPE_TAG]: "image",
-          metadata
-        })));
-      } else {
-        return result.ok({
-          [FILE_REF_PROP]: ref.text,
-          _type: "file",
-          [FILE_REF_SUBTYPE_TAG]: "image"
-        });
-      }
-    }));
-  } else if (isValRemoteMethodCall(value)) {
-    return pipe(findValRemoteNodeArg(value), result.flatMap(ref => {
-      if (value.arguments.length === 2) {
-        return pipe(evaluateExpression(value.arguments[1]), result.map(metadata => ({
-          [FILE_REF_PROP]: ref.text,
-          _type: "remote",
-          metadata
-        })));
-      } else {
-        return result.ok({
-          [FILE_REF_PROP]: ref.text,
-          _type: "remote"
-        });
-      }
-    }));
   } else {
-    return result.err(new ValSyntaxError("Expression must be a literal or call c.file / c.image / c.remote", value));
+    return result.err(new ValSyntaxError("Expression must be a literal", value));
   }
 }
 function findObjectPropertyAssignment(value, key) {
@@ -156,93 +110,6 @@ function findObjectPropertyAssignment(value, key) {
     return result.ok(assignment);
   }));
 }
-function isValFileMethodCall(node) {
-  return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === "c" && node.expression.name.text === "file";
-}
-function isValImageMethodCall(node) {
-  return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === "c" && node.expression.name.text === "image";
-}
-function isValRemoteMethodCall(node) {
-  return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === "c" && node.expression.name.text === "remote";
-}
-function findValFileNodeArg(node) {
-  if (node.arguments.length === 0) {
-    return result.err(new ValSyntaxError(`Invalid c.file() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return result.err(new ValSyntaxError(`Invalid c.file() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (!ts.isStringLiteral(node.arguments[0])) {
-    return result.err(new ValSyntaxError(`Invalid c.file() call: ref must be a string literal`, node));
-  }
-  const refNode = node.arguments[0];
-  return result.ok(refNode);
-}
-function findValRemoteNodeArg(node) {
-  if (node.arguments.length === 0) {
-    return result.err(new ValSyntaxError(`Invalid c.remote() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return result.err(new ValSyntaxError(`Invalid c.remote() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (!ts.isStringLiteral(node.arguments[0])) {
-    return result.err(new ValSyntaxError(`Invalid c.remote() call: ref must be a string literal`, node));
-  }
-  const refNode = node.arguments[0];
-  return result.ok(refNode);
-}
-function findValImageNodeArg(node) {
-  if (node.arguments.length === 0) {
-    return result.err(new ValSyntaxError(`Invalid c.image() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return result.err(new ValSyntaxError(`Invalid c.image() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (!ts.isStringLiteral(node.arguments[0])) {
-    return result.err(new ValSyntaxError(`Invalid c.image() call: ref must be a string literal`, node));
-  }
-  const refNode = node.arguments[0];
-  return result.ok(refNode);
-}
-function findValFileMetadataArg(node) {
-  if (node.arguments.length === 0) {
-    return result.err(new ValSyntaxError(`Invalid c.file() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return result.err(new ValSyntaxError(`Invalid c.file() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (node.arguments.length === 2) {
-    if (!ts.isObjectLiteralExpression(node.arguments[1])) {
-      return result.err(new ValSyntaxError(`Invalid c.file() call: metadata must be a object literal`, node));
-    }
-    return result.ok(node.arguments[1]);
-  }
-  return result.ok(undefined);
-}
-function findValImageMetadataArg(node) {
-  if (node.arguments.length === 0) {
-    return result.err(new ValSyntaxError(`Invalid c.image() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return result.err(new ValSyntaxError(`Invalid c.image() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (node.arguments.length === 2) {
-    if (!ts.isObjectLiteralExpression(node.arguments[1])) {
-      return result.err(new ValSyntaxError(`Invalid c.image() call: metadata must be a object literal`, node));
-    }
-    return result.ok(node.arguments[1]);
-  }
-  return result.ok(undefined);
-}
-function findValRemoteMetadataArg(node) {
-  if (node.arguments.length === 0) {
-    return result.err(new ValSyntaxError(`Invalid c.remote() call: missing ref argument`, node));
-  } else if (node.arguments.length > 2) {
-    return result.err(new ValSyntaxError(`Invalid c.remote() call: too many arguments ${node.arguments.length}}`, node));
-  } else if (node.arguments.length === 2) {
-    if (!ts.isObjectLiteralExpression(node.arguments[1])) {
-      return result.err(new ValSyntaxError(`Invalid c.remote() call: metadata must be a object literal`, node));
-    }
-    return result.ok(node.arguments[1]);
-  }
-  return 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.isSpreadElement(node)) {
@@ -324,27 +191,6 @@ function isValidIdentifier(text) {
 function createPropertyAssignment(key, value) {
   return ts.factory.createPropertyAssignment(isValidIdentifier(key) ? ts.factory.createIdentifier(key) : ts.factory.createStringLiteral(key), toExpression(value));
 }
-function createValFileReference(value) {
-  const args = [ts.factory.createStringLiteral(value[FILE_REF_PROP])];
-  if (value.metadata) {
-    args.push(toExpression(value.metadata));
-  }
-  return ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("c"), ts.factory.createIdentifier("file")), undefined, args);
-}
-function createValImageReference(value) {
-  const args = [ts.factory.createStringLiteral(value[FILE_REF_PROP])];
-  if (value.metadata) {
-    args.push(toExpression(value.metadata));
-  }
-  return ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("c"), ts.factory.createIdentifier("image")), undefined, args);
-}
-function createValRemoteReference(value) {
-  const args = [ts.factory.createStringLiteral(value[FILE_REF_PROP])];
-  if (value.metadata) {
-    args.push(toExpression(value.metadata));
-  }
-  return ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("c"), ts.factory.createIdentifier("remote")), undefined, args);
-}
 
 /**
  * Builds the expression `c.json(() => import("<importPath>"))` used to reference
@@ -430,16 +276,12 @@ function toExpression(value) {
   } else if (Array.isArray(value)) {
     return ts.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.factory.createObjectLiteralExpression(Object.entries(value).map(([key, value]) => createPropertyAssignment(key, value)));
+    return ts.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.factory.createStringLiteral(value);
   }
@@ -572,63 +414,6 @@ function replaceInNode(document, node, key, value) {
       }
       return result.ok(assignment);
     }), result.map(assignment => replaceNodeValue(document, assignment.initializer, value)));
-  } else if (isValFileMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return result.err(new PatchError("Cannot replace c.file reference with non-string value"));
-      }
-      return pipe(findValFileNodeArg(node), result.map(refNode => replaceNodeValue(document, refNode, value)));
-    } else {
-      return pipe(findValFileMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return result.err(new PatchError("Cannot replace in c.file metadata when it does not exist"));
-        }
-        if (key !== "metadata") {
-          return result.err(new 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.factory.createObjectLiteralExpression([ts.factory.createPropertyAssignment(key, metadataArgNode)]), key, value);
-      }));
-    }
-  } else if (isValImageMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return result.err(new PatchError("Cannot replace c.image reference with non-string value"));
-      }
-      return pipe(findValImageNodeArg(node), result.map(refNode => replaceNodeValue(document, refNode, value)));
-    } else {
-      return pipe(findValImageMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return result.err(new PatchError("Cannot replace in c.image metadata when it does not exist"));
-        }
-        if (key !== "metadata") {
-          return result.err(new 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.factory.createObjectLiteralExpression([ts.factory.createPropertyAssignment(key, metadataArgNode)]), key, value);
-      }));
-    }
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return result.err(new PatchError("Cannot replace c.image reference with non-string value"));
-      }
-      return pipe(findValRemoteNodeArg(node), result.map(refNode => replaceNodeValue(document, refNode, value)));
-    } else {
-      return pipe(findValRemoteMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return result.err(new PatchError("Cannot replace in c.remote metadata when it does not exist"));
-        }
-        if (key !== "metadata") {
-          return result.err(new 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.factory.createObjectLiteralExpression([ts.factory.createPropertyAssignment(key, metadataArgNode)]), key, value);
-      }));
-    }
   } else {
     return result.err(shallowValidateExpression(node) ?? new PatchError("Cannot replace in non-object/array"));
   }
@@ -645,21 +430,6 @@ function getFromNode(node, key) {
     return pipe(parseAndValidateArrayInboundsIndex(key, node.elements), result.map(index => node.elements[index]));
   } else if (ts.isObjectLiteralExpression(node)) {
     return pipe(findObjectPropertyAssignment(node, key), result.map(assignment => assignment === null || assignment === void 0 ? void 0 : assignment.initializer));
-  } else if (isValFileMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      return findValFileNodeArg(node);
-    }
-    return findValFileMetadataArg(node);
-  } else if (isValImageMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      return findValImageNodeArg(node);
-    }
-    return findValImageMetadataArg(node);
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      return findValRemoteNodeArg(node);
-    }
-    return findValRemoteMetadataArg(node);
   } else {
     return result.err(shallowValidateExpression(node) ?? new PatchError("Cannot access non-object/array"));
   }
@@ -692,39 +462,6 @@ function removeFromNode(document, node, key) {
       }
       return result.ok(assignment);
     }), result.map(assignment => [removeAt(document, node.properties, node.properties.indexOf(assignment))[0], assignment.initializer]));
-  } else if (isValFileMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      return result.err(new PatchError("Cannot remove a ref from c.file"));
-    } else {
-      return pipe(findValFileMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return result.err(new PatchError("Cannot remove from c.file metadata when it does not exist"));
-        }
-        return removeFromNode(document, metadataArgNode, key);
-      }));
-    }
-  } else if (isValImageMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      return result.err(new PatchError("Cannot remove a ref from c.image"));
-    } else {
-      return pipe(findValImageMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return result.err(new PatchError("Cannot remove from c.image metadata when it does not exist"));
-        }
-        return removeFromNode(document, metadataArgNode, key);
-      }));
-    }
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      return result.err(new PatchError("Cannot remove a ref from c.remote"));
-    } else {
-      return pipe(findValRemoteMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (!metadataArgNode) {
-          return result.err(new PatchError("Cannot remove from c.remote metadata when it does not exist"));
-        }
-        return removeFromNode(document, metadataArgNode, key);
-      }));
-    }
   } else {
     return result.err(shallowValidateExpression(node) ?? new PatchError("Cannot remove from non-object/array"));
   }
@@ -732,22 +469,10 @@ function removeFromNode(document, node, key) {
 function removeAtPath(document, rootNode, path) {
   return pipe(getPointerFromPath(rootNode, path), result.flatMap(([node, key]) => removeFromNode(document, node, key)));
 }
-function isValFileValue(value) {
-  return !!(typeof value === "object" && value && VAL_EXTENSION in value && value[VAL_EXTENSION] === "file" && FILE_REF_PROP in value && typeof value[FILE_REF_PROP] === "string" && value[FILE_REF_SUBTYPE_TAG] !== "image");
-}
-function isValImageValue(value) {
-  return !!(typeof value === "object" && value && VAL_EXTENSION in value && value[VAL_EXTENSION] === "file" && FILE_REF_PROP in value && typeof value[FILE_REF_PROP] === "string" && value[FILE_REF_SUBTYPE_TAG] === "image");
-}
-function isValRemoteValue(value) {
-  return !!(typeof value === "object" && value && VAL_EXTENSION in value && value[VAL_EXTENSION] === "remote" && FILE_REF_PROP in value && typeof value[FILE_REF_PROP] === "string");
-}
 function addToNode(document, node, key, value) {
   if (ts.isArrayLiteralExpression(node)) {
     return pipe(parseAndValidateArrayInsertIndex(key, node.elements), result.map(index => [insertAt(document, node.elements, index, toExpression(value))]));
   } else if (ts.isObjectLiteralExpression(node)) {
-    if (key === FILE_REF_PROP) {
-      return result.err(new PatchError("Cannot add a key ref to object"));
-    }
     return pipe(findObjectPropertyAssignment(node, key), result.map(assignment => {
       if (!assignment) {
         return [insertAt(document, node.properties, node.properties.length, createPropertyAssignment(key, value))];
@@ -755,57 +480,6 @@ function addToNode(document, node, key, value) {
         return replaceNodeValue(document, assignment.initializer, value);
       }
     }));
-  } else if (isValFileMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return result.err(new PatchError(`Cannot add ${FILE_REF_PROP} key to c.file with non-string value`));
-      }
-      return pipe(findValFileNodeArg(node), result.map(arg => replaceNodeValue(document, arg, value)));
-    } else {
-      return pipe(findValFileMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (metadataArgNode) {
-          return result.err(new PatchError("Cannot add metadata to c.file when it already exists"));
-        }
-        if (key !== "metadata") {
-          return result.err(new PatchError(`Cannot add ${key} key to c.file: only metadata is allowed`));
-        }
-        return result.ok([insertAt(document, node.arguments, node.arguments.length, toExpression(value))]);
-      }));
-    }
-  } else if (isValImageMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return result.err(new PatchError(`Cannot add ${FILE_REF_PROP} key to c.image with non-string value`));
-      }
-      return pipe(findValImageNodeArg(node), result.map(arg => replaceNodeValue(document, arg, value)));
-    } else {
-      return pipe(findValImageMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (metadataArgNode) {
-          return result.err(new PatchError("Cannot add metadata to c.image when it already exists"));
-        }
-        if (key !== "metadata") {
-          return result.err(new PatchError(`Cannot add ${key} key to c.image: only metadata is allowed`));
-        }
-        return result.ok([insertAt(document, node.arguments, node.arguments.length, toExpression(value))]);
-      }));
-    }
-  } else if (isValRemoteMethodCall(node)) {
-    if (key === FILE_REF_PROP) {
-      if (typeof value !== "string") {
-        return result.err(new PatchError(`Cannot add ${FILE_REF_PROP} key to c.remote with non-string value`));
-      }
-      return pipe(findValRemoteNodeArg(node), result.map(arg => replaceNodeValue(document, arg, value)));
-    } else {
-      return pipe(findValRemoteMetadataArg(node), result.flatMap(metadataArgNode => {
-        if (metadataArgNode) {
-          return result.err(new PatchError("Cannot add metadata to c.remote when it already exists"));
-        }
-        if (key !== "metadata") {
-          return result.err(new PatchError(`Cannot add ${key} key to c.remote: only metadata is allowed`));
-        }
-        return result.ok([insertAt(document, node.arguments, node.arguments.length, toExpression(value))]);
-      }));
-    }
   } else {
     return result.err(shallowValidateExpression(node) ?? new PatchError("Cannot add to non-object/array"));
   }
@@ -1387,7 +1061,10 @@ function rebaseContentOp(op, prefixLen) {
         from: op.from.slice(prefixLen)
       });
     case "file":
-      return result.err(new 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 result.err(new PatchError("A file op is not a content op: rebase it via its path"));
   }
 }
 
@@ -1421,9 +1098,6 @@ function applyJsonValuesEntryPatches(args) {
   } of patches) {
     let touched = false;
     for (const op of patch) {
-      if (op.op === "file") {
-        continue;
-      }
       const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
         kind: "normal"
       };
@@ -1431,6 +1105,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 = applyPatch(deepClone(content), jsonOps$1, [{
+          op: "add",
+          path: cls.subPath.concat(...(op.nestedFilePath ?? [])).concat("patch_id"),
+          value: patchId
+        }]);
+        if (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;
@@ -1528,6 +1228,35 @@ function resolveExistingJsonPath(moduleFilePath, importPath) {
  * module errors (see `findNestedJsonValuesRecords`), so they can never reach
  * here — if that guard is ever relaxed, this must become a recursive visitor or
  * nested entries silently get no content validation at all.
+ *
+ * ## NOT validated, and it should be: the entry's FILE PATH
+ *
+ * The key↔file mapping is canonical. `getNewJsonEntryPaths` derives it, and both
+ * write paths use it — the `jsonValues:extract-entry` fix and the patch commit:
+ *
+ *     /content/kb.val.ts  +  key "kb-000"  ->  /content/kb/kb-000.val.json
+ *
+ * This function does not check it. It calls the thunk and validates whatever
+ * comes back, so an entry may point at ANY file in the project and pass. The
+ * repo's own fixture does exactly that — `examples/next/content/kb.val.ts` has
+ * `"kb-000": c.json(() => import("./kb/entry-000.val.json"))`, where the
+ * canonical path is `./kb/kb-000.val.json`, and `val validate` calls it valid.
+ *
+ * Two consequences, the first a live bug:
+ *
+ * - **A key rename writes to the DERIVED path**, which for a non-canonical entry
+ *   is not the file the old key was reading. The old file is orphaned and the new
+ *   key reads a file that was never written.
+ * - It blocks localising entry staleness. `jsonEntriesSha` cannot say which entry
+ *   changed, so the client drops a whole module's loaded content; with the mapping
+ *   guaranteed, a changed file resolves to one key by derivation alone.
+ *
+ * The fix belongs here and needs no new machinery: the module's `.val.ts` is
+ * already parsed (`ValSourceFileHandler`), so the import specifier is readable
+ * from the AST — no `thunk.toString()`, which a bundler would defeat. A
+ * `jsonValues:rename-entry-file` fix could move the file and rewrite the import,
+ * exactly as `extract-entry` writes both. See `packages/ui/spa/stores/openquestions.md`
+ * item 9b.
  */
 async function validateJsonValuesEntries(schema, source, modulePath) {
   const out = {};
@@ -2374,6 +2103,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)
@@ -2674,7 +2414,7 @@ class ValOps {
         };
       }
       const type = schemaAtPath instanceof ImageSchema ? "image" : "file";
-      const filePath = value[FILE_REF_PROP];
+      const filePath = value.path;
       const fileData = (fileLastUpdatedByPatchId === null || fileLastUpdatedByPatchId === void 0 ? void 0 : fileLastUpdatedByPatchId[filePath]) || null;
       let metadata;
       let metadataErrors;
@@ -2716,23 +2456,14 @@ class ValOps {
           }]
         };
       }
-      const metadataSourcePath = 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 = Internal.createValPathOfItem(metadataSourcePath, field);
+        const fieldSourcePath = Internal.createValPathOfItem(sourcePath, field);
         if (!fieldSourcePath) {
           throw new Error("Could not create field path");
         }
@@ -3324,11 +3055,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 && FILE_REF_PROP in value && VAL_EXTENSION in value && value[VAL_EXTENSION] === "file" && 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) {
@@ -4672,7 +4407,7 @@ const FSPatchBase = z.object({
   timestamp: z.string().datetime()
 });
 
-const textEncoder$1 = new TextEncoder();
+const textEncoder$2 = new TextEncoder();
 const PatchId = z.string().refine(s => !!s); // TODO: validate
 const CommitSha = z.string().refine(s => !!s); // TODO: validate
 z.string().refine(s => !!s); // TODO: validate
@@ -5363,7 +5098,7 @@ class ValOpsHttp extends ValOps {
     });
     params.set("body_sha",
     // We use this for cache invalidation
-    Internal.getSHA256Hash(textEncoder$1.encode(stringifiedFiles)));
+    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.
@@ -5789,51 +5524,6 @@ function parsePersonalAccessTokenFile(content) {
   }
 }
 
-/**
- * Iterates through all schemas and find if there is 1 or more remote files in them
- */
-function hasRemoteFileSchema(schema) {
-  if (schema.type === "file" || schema.type === "image") {
-    return !!schema.remote;
-  } else if (schema.type === "richtext") {
-    var _schema$options;
-    if (typeof ((_schema$options = schema.options) === null || _schema$options === void 0 || (_schema$options = _schema$options.inline) === null || _schema$options === void 0 ? void 0 : _schema$options.img) === "object") {
-      return hasRemoteFileSchema(schema.options.inline.img);
-    }
-    return false;
-  } else if (schema.type === "array" || schema.type === "record") {
-    return hasRemoteFileSchema(schema.item);
-  } else if (schema.type === "object") {
-    for (const key in schema.items) {
-      const hasRemoteFile = hasRemoteFileSchema(schema.items[key]);
-      if (hasRemoteFile) {
-        return true;
-      }
-    }
-    return false;
-  } else if (schema.type === "union") {
-    const unionStringSchema = typeof schema.key === "object" && schema.key.type === "literal" ? schema : undefined;
-    const unionObjectSchema = typeof schema.key === "string" ? schema : undefined;
-    if (unionStringSchema) {
-      return false;
-    }
-    if (unionObjectSchema) {
-      for (const key in unionObjectSchema.items) {
-        const hasRemoteFile = hasRemoteFileSchema(unionObjectSchema.items[key]);
-        if (hasRemoteFile) {
-          return true;
-        }
-      }
-    }
-    return false;
-  } else if (schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "keyOf" || schema.type === "route") {
-    return false;
-  } else {
-    const exhaustiveCheck = schema;
-    throw new Error(`Unexpected schema: ${JSON.stringify(exhaustiveCheck)}`);
-  }
-}
-
 /* eslint-disable @typescript-eslint/no-unused-vars */
 const ValServer = (valModules, options, callbacks) => {
   const AIContentBlock = z.union([z.object({
@@ -9136,15 +8826,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" && FILE_REF_PROP in validationError.value && typeof validationError.value[FILE_REF_PROP] === "string" ? validationError.value[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 = Internal.remote.splitRemoteRef(ref);
   if (remoteRefDataRes.status === "error") {
@@ -9174,10 +8870,10 @@ async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
   const fileExt = getFileExt(relativeFilePath);
   const currentValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, metadata,
   // TODO: validate
-  fileHash, textEncoder);
+  fileHash, textEncoder$1);
   const validationHashFromRemoteRefValues = 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
@@ -9223,7 +8919,7 @@ async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
     ...metadata,
     ...currentMetadata
   };
-  const nextValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, updatedMetadata, fileBufferRes.fileHash, textEncoder);
+  const nextValidationHash = Internal.remote.getValidationHash(coreVersion, schema, fileExt, updatedMetadata, fileBufferRes.fileHash, textEncoder$1);
   if (!updatedMetadata.mimeType) {
     return {
       status: "error",
@@ -9353,6 +9049,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 = [];
@@ -9366,57 +9092,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.push({
-              op: "replace",
-              path: 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.push({
+                op: "add",
+                path: 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") {
@@ -9427,14 +9134,19 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
             fixes: undefined
           });
         } else {
+          const patchPath = sourceToPatchPath(sourcePath);
           patch.push({
             op: "add",
-            path: 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
           });
         }
       }
@@ -9447,53 +9159,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.push({
-              op: "replace",
-              path: sourceToPatchPath(sourcePath).concat("metadata"),
-              value: {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                ...currentValue.metadata,
-                ...(fileMetadata.mimeType ? {
-                  mimeType: fileMetadata.mimeType
-                } : {})
-              }
+              op: "add",
+              path: 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.push({
           op: "add",
-          path: sourceToPatchPath(sourcePath).concat("metadata"),
-          value: {
-            ...(fileMetadata.mimeType ? {
-              mimeType: fileMetadata.mimeType
-            } : {})
-          }
+          path: sourceToPatchPath(sourcePath).concat("mimeType"),
+          value: fileMetadata.mimeType ?? null
         });
       }
     } else if (fix === "image:upload-remote" || fix === "file:upload-remote") {
@@ -9521,11 +9212,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
       } else {
         patch.push({
           op: "replace",
-          value: {
-            _type: "remote",
-            _ref: remoteFile.ref,
-            metadata
-          },
+          value: mediaValue(remoteFile.ref, metadata),
           path: sourceToPatchPath(sourcePath)
         });
       }
@@ -9594,7 +9281,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         });
         continue;
       }
-      const splitRemoteRefDataRes = Internal.remote.splitRemoteRef(v._ref);
+      const splitRemoteRefDataRes = Internal.remote.splitRemoteRef(v.path);
       if (splitRemoteRefDataRes.status === "error") {
         remainingErrors.push({
           ...validationError,
@@ -9603,7 +9290,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({
@@ -9634,20 +9321,10 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         });
         continue;
       }
-      const value = {
-        [VAL_EXTENSION]: "file",
-        [FILE_REF_PROP]: `/${filePath}`,
-        ...(fix === "image:download-remote" ? {
-          [FILE_REF_SUBTYPE_TAG]: "image"
-        } : {})
-      };
       patch.push({
         op: "replace",
         path: 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") {
@@ -9770,7 +9447,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         schema: schemaAtPath
       } = 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,
@@ -9782,11 +9459,7 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
             patch.push({
               op: "replace",
               path: sourceToPatchPath(sourcePath),
-              value: {
-                _type: "remote",
-                _ref: res.ref,
-                metadata: res.metadata
-              }
+              value: mediaValue(res.ref, res.metadata)
             });
           } else {
             remainingErrors.push({
@@ -9833,37 +9506,26 @@ function getRemoteValueFromValidationError(v) {
       message: "Unexpected error while checking remote (no value)"
     };
   }
-  if (typeof v.value !== "object" || v.value === null || !(FILE_REF_PROP in v.value)) {
+  if (typeof v.value !== "object" || v.value === null || !("path" in v.value)) {
     return {
       success: false,
-      message: "Unexpected error while checking remote (no _ref in value)"
+      message: "Unexpected error while checking remote (no path in value)"
     };
   }
-  if (typeof v.value._ref !== "string") {
+  if (typeof v.value.path !== "string") {
     return {
       success: false,
-      message: "Unexpected error while checking remote (_ref is not a string)"
+      message: "Unexpected error while checking remote (path is not a string)"
     };
   }
-  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 (Array.isArray(v.value.metadata)) {
-      return {
-        success: false,
-        message: "Unexpected error while checking remote (metadata is an array)"
-      };
-    }
-    metadata = v.value.metadata;
-  }
+  // Everything but the path is what Val read from the bytes.
+  const {
+    path,
+    ...metadata
+  } = v.value;
   return {
     success: true,
-    _ref: v.value._ref,
+    path,
     metadata
   };
 }
@@ -9888,25 +9550,651 @@ async function getFileMetadata(projectRoot, validationError) {
   return extractFileMetadata(fileRef);
 }
 
-function validateMetadata(actualMetadata, expectedMetadata) {
-  const missingMetadata = [];
-  const erroneousMetadata = {};
-  if (typeof actualMetadata !== "object" || actualMetadata === null) {
-    return {
-      globalErrors: ["Metadata is wrong type: must be an object."]
-    };
-  }
-  if (Array.isArray(actualMetadata)) {
-    return {
-      globalErrors: ["Metadata is wrong type: cannot be an array."]
-    };
-  }
-  const recordMetadata = actualMetadata;
-  const globalErrors = [];
-  for (const anyKey in expectedMetadata) {
-    if (typeof anyKey !== "string") {
-      globalErrors.push(`Expected metadata has key '${anyKey}' that is not typeof 'string', but: '${typeof anyKey}'. This is most likely a Val bug.`);
-    } else {
+/**
+ * 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 (result.isErr(pathsRes)) {
+    throw Error(formatPatchSourceError(pathsRes.error));
+  }
+  const {
+    jsonPath,
+    importPath
+  } = pathsRes.value;
+  const absoluteJsonPath = path__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 (result.isErr(removed)) {
+    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
+  }
+  const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
+  if (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 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] = 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 = 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__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__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__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__default.relative(ctx.projectRoot, filePath).split(path__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 = Internal.remote.getFileHash(fileBuffer);
+  const coreVersion = Internal.VERSION.core || "unknown";
+  const fileExt = getFileExt(filePath);
+  const ref = Internal.remote.createRemoteRef(ctx.remote.remoteHost, {
+    publicProjectId,
+    coreVersion,
+    bucket,
+    validationHash: 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 {
+    success: true,
+    shouldApplyPatch: true,
+    publicProjectId,
+    remoteFileBuckets,
+    remoteFilesCounter,
+    events: [{
+      type: "remote-uploading",
+      ref
+    }, {
+      type: "remote-uploaded",
+      ref
+    }]
+  };
+}
+async function handleRemoteFileUpload(ctx) {
+  var _resolvedRemoteFileAt;
+  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 [, modulePath] = 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 resolvedRemoteFileAtSourcePath = 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,
+      errorMessage: `Expected file to be defined at: ${ctx.sourcePath} but no file was found`
+    };
+  }
+  const resolveRemoteFileSchema = resolvedRemoteFileAtSourcePath.schema;
+  if (!resolveRemoteFileSchema) {
+    return {
+      success: false,
+      errorMessage: `Cannot upload remote file: schema not found for ${ctx.sourcePath}`
+    };
+  }
+  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] = 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 = 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] = Internal.splitModuleFilePathAndModulePath(Internal.parentOfSourcePath(ctx.sourcePath));
+  const recordSchema = 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 (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 = 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__default.join(ctx.projectRoot, f));
+  });
+  if (missingTrackedFiles.length > 0) {
+    if (!ctx.fix) {
+      return {
+        success: false,
+        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.`
+      };
+    }
+    // fix: true — let createFixPatch remove the missing entries
+    return {
+      success: true,
+      shouldApplyPatch: true
+    };
+  }
+  const dirPath = path__default.join(ctx.projectRoot, directory);
+  const filesInDir = [];
+  try {
+    const entries = ctx.fs.readDirectory(dirPath, undefined, undefined, ["**/*"]);
+    for (const entry of entries) {
+      const relPath = "/" + path__default.relative(ctx.projectRoot, entry).split(path__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,
+    shouldApplyPatch: true
+  };
+}
+async function handleJsonValuesExtractEntry(ctx) {
+  const [, modulePath] = Internal.splitModuleFilePathAndModulePath(ctx.sourcePath);
+  const parts = 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 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 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.sys,
+    writeFile: (fileName, data, encoding) => {
+      fs.mkdirSync(path__default.dirname(fileName), {
+        recursive: true
+      });
+      fs.writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
+    },
+    rmFile: fs.rmSync,
+    readBuffer: fileName => {
+      try {
+        return fs.readFileSync(fileName);
+      } catch {
+        return undefined;
+      }
+    }
+  };
+}
+
+function validateMetadata(actualMetadata, expectedMetadata) {
+  const missingMetadata = [];
+  const erroneousMetadata = {};
+  if (typeof actualMetadata !== "object" || actualMetadata === null) {
+    return {
+      globalErrors: ["Metadata is wrong type: must be an object."]
+    };
+  }
+  if (Array.isArray(actualMetadata)) {
+    return {
+      globalErrors: ["Metadata is wrong type: cannot be an array."]
+    };
+  }
+  const recordMetadata = actualMetadata;
+  const globalErrors = [];
+  for (const anyKey in expectedMetadata) {
+    if (typeof anyKey !== "string") {
+      globalErrors.push(`Expected metadata has key '${anyKey}' that is not typeof 'string', but: '${typeof anyKey}'. This is most likely a Val bug.`);
+    } else {
       if (anyKey in actualMetadata) {
         const key = anyKey;
         if (expectedMetadata[key] !== recordMetadata[key]) {
@@ -10180,9 +10468,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
@@ -10235,7 +10523,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) {
@@ -10299,39 +10587,6 @@ function traverse(node, sourceFile) {
   if (ts.isArrayLiteralExpression(node)) {
     return traverseArrayLiteral(node, sourceFile);
   }
-  if (ts.isCallExpression(node)) {
-    return traverseCallExpression(node, sourceFile);
-  }
-}
-function traverseCallExpression(node, sourceFile) {
-  if (ts.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) => {
@@ -10405,61 +10660,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 (result.isErr(pathsRes)) {
-    throw Error(formatPatchSourceError(pathsRes.error));
-  }
-  const {
-    jsonPath,
-    importPath
-  } = pathsRes.value;
-  const absoluteJsonPath = path__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 (result.isErr(removed)) {
-    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
-  }
-  const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
-  if (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 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.
@@ -10559,4 +10759,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValServer, decodeJwt, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, hasRemoteFileSchema, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };
+export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValServer, currentFixHandlers, decodeJwt, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };