@valbuild/server 0.131.0 → 0.132.1

package/dist/valbuild-server.esm.js

@@ -1,7 +1,7 @@
 import ts from 'typescript';
 import { pipe, result, array } from '@valbuild/core/fp';
 import { PatchError, deepEqual, parseAndValidateArrayIndex, isNotRoot, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
-import { derefPatch, Internal, extractValModules, computeValModuleShas, VAL_EXTENSION, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema } from '@valbuild/core';
+import { derefPatch, Internal, VAL_EXTENSION, extractValModules, computeValModuleShas, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema } from '@valbuild/core';
 export { hasRemoteFileSchema } from '@valbuild/core';
 import * as path from 'path';
 import path__default from 'path';
@@ -1097,6 +1097,176 @@ function descend(schema, key) {
   }
 }
 
+/**
+ * Is this op a write of the WHOLE record at the root of a `.jsonValues()`
+ * module?
+ *
+ * The one op {@link classifyJsonValuesOp} cannot classify: it finds the entry
+ * key by walking the op path, and the root path has no segments to walk, so a
+ * root write reads as `normal` and gets applied to the `.val.ts` - writing
+ * markers over the `c.json(() => import(...))` calls that make the entries load
+ * at all. {@link expandJsonValuesRootOp} turns it into ops that DO name a key,
+ * which everything downstream already handles.
+ *
+ * `add` counts as well as `replace`: at the root both mean "the document is now
+ * this" (see `JSONOps`), so both have to be expanded or the unexpanded one is
+ * the same bug again.
+ *
+ * The value has to BE a record, and that is part of the question rather than a
+ * check inside the expansion: a `.jsonValues()` record can be nullable, and
+ * `null` at the root means the module no longer has a record at all - there are
+ * no entries to write, and it is an ordinary `.val.ts` write, exactly as it was
+ * before any of this existed. Same for any other non-record value: not a
+ * whole-record write, so not this conversion's to route.
+ */
+function isJsonValuesRootOp(schema, op) {
+  return (op.op === "replace" || op.op === "add") && op.path.length === 0 && isJsonValuesRecord$1(op.value) && schema.type === "record" && schema.jsonValues === true;
+}
+function isJsonValuesRecord$1(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * One entry as it stands right now, for {@link expandJsonValuesRootOp} to
+ * expand against.
+ *
+ * The key set decides add-vs-replace-vs-remove. The content, where the caller
+ * has it, decides whether an op is emitted at all: an entry whose content is
+ * already what the root write says is left alone rather than rewritten, so
+ * putting a module back does not touch every `*.val.json` it did not change.
+ * `undefined` means "this entry exists, content unknown" - which is what the
+ * Studio's draft source has, because the source holds markers - and yields a
+ * `replace`, the safe answer.
+ */
+
+/**
+ * Fans a whole-record write at a `.jsonValues()` module's root out into ops
+ * that each name an entry key.
+ *
+ * This is THE conversion, and it has exactly one implementation on purpose: the
+ * commit flow (`ValOps.prepare`) and the read side that builds draft content
+ * ({@link applyJsonValuesEntryPatches}) both expand through here, so a draft
+ * cannot show something other than what publishing writes. A second
+ * implementation of the same rule would differ silently, which is the whole
+ * failure mode this exists to prevent.
+ *
+ * The value must be the entries' CONTENT. A module's Source is markers, not
+ * content, so a Source handed over here is refused rather than written: that is
+ * the shape of the original bug (a revert replaying the archived Source), and
+ * it is not recoverable afterwards - the markers replace the entries' content
+ * on disk.
+ */
+function expandJsonValuesRootOp(op, currentEntries) {
+  const valueRes = jsonValuesRootValue(op);
+  if (result.isErr(valueRes)) {
+    return valueRes;
+  }
+  const value = valueRes.value;
+  const expanded = [];
+  for (const entryKey of Object.keys(value)) {
+    const write = writeForEntry(value, entryKey, currentEntries);
+    if (write !== null) {
+      expanded.push(write);
+    }
+  }
+  for (const entryKey of currentEntries.keys()) {
+    if (!Object.prototype.hasOwnProperty.call(value, entryKey)) {
+      expanded.push({
+        op: "remove",
+        path: [entryKey]
+      });
+    }
+  }
+  return result.ok(expanded);
+}
+
+/**
+ * What a whole-record write says about ONE entry: the same rule
+ * {@link expandJsonValuesRootOp} applies to all of them.
+ *
+ * For a reader that is about one entry. Expanding the whole record to find the
+ * one op that names its key costs an op per entry per entry read - the record
+ * squared, on exactly the large records this feature is for. The rule itself is
+ * `writeForEntry`, shared with the expansion above, so the two cannot come to
+ * disagree; only the loop around it differs.
+ *
+ * `null` means the write says nothing about this entry: it holds that content
+ * already, or the record does not name it and it does not exist.
+ */
+function expandJsonValuesRootOpForKey(op, entryKey, currentEntries) {
+  const valueRes = jsonValuesRootValue(op);
+  if (result.isErr(valueRes)) {
+    return valueRes;
+  }
+  const value = valueRes.value;
+  if (Object.prototype.hasOwnProperty.call(value, entryKey)) {
+    return result.ok(writeForEntry(value, entryKey, currentEntries));
+  }
+  if (currentEntries.has(entryKey)) {
+    return result.ok({
+      op: "remove",
+      path: [entryKey]
+    });
+  }
+  return result.ok(null);
+}
+
+/**
+ * The record a whole-record write carries, once it is known to be one.
+ *
+ * Every entry's value is checked here rather than where each one is written:
+ * a marker anywhere in the record means the writer handed over a module's
+ * Source, and the answer to that is to refuse the write, not to write the rest
+ * of it. Both entry points ask, so an entry read reports it too rather than
+ * showing a draft of a patch that publishing will refuse.
+ */
+function jsonValuesRootValue(op) {
+  if (op.op !== "replace" && op.op !== "add") {
+    return result.err(new PatchError(`Cannot '${op.op}' the root of a .jsonValues() record: only add and replace write the whole record`));
+  }
+  const value = op.value;
+  if (!isJsonValuesRecord$1(value)) {
+    return result.err(new PatchError("Cannot write the root of a .jsonValues() record with a non-record value: it must be an object of entry key to entry content"));
+  }
+  for (const entryKey of Object.keys(value)) {
+    /*
+     * A marker is what a module's Source holds WHERE THE CONTENT IS NOT: it
+     * says the content is in the entry's own file. Handed back as an entry's
+     * value - which is what replaying an archived Source does - it would
+     * replace that content with the note saying where it used to be, and
+     * nothing downstream could tell the difference.
+     */
+    if (Internal.isJson(value[entryKey])) {
+      return result.err(new PatchError(`Cannot write the .jsonValues() entry '${entryKey}' from a '${VAL_EXTENSION}: "json"' marker: a marker says the content is in the entry's own file, so write the entry's CONTENT here, not the module's Source`));
+    }
+  }
+  return result.ok(value);
+}
+
+/** THE rule, for one entry the record names. `null` = nothing to write. */
+function writeForEntry(value, entryKey, currentEntries) {
+  const content = value[entryKey];
+  if (!currentEntries.has(entryKey)) {
+    return {
+      op: "add",
+      path: [entryKey],
+      value: content
+    };
+  }
+  const current = currentEntries.get(entryKey);
+  if (current !== undefined && deepEqual(current, content)) {
+    // Unchanged: emitting a replace here would rewrite the entry's file with
+    // the bytes it already holds, so putting a module back would show up as a
+    // change to every entry in it.
+    return null;
+  }
+  return {
+    op: "replace",
+    path: [entryKey],
+    value: content
+  };
+}
+
 /**
  * Finds every `.jsonValues()` record in a module's schema that is NOT the
  * module's root, returning the path to each within the module source.
@@ -1270,88 +1440,110 @@ function applyJsonValuesEntryPatches(args) {
     patch
   } of patches) {
     let touched = false;
-    for (const op of patch) {
-      const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
-        kind: "normal"
-      };
-      if (cls.kind !== "entry" || cls.recordPath.length > 0 || cls.entryKey !== entryKey) {
-        continue;
+    for (const rawOp of patch) {
+      /**
+       * A write of the WHOLE record becomes what it says about THIS entry.
+       *
+       * Through the same rule the commit flow expands with, against the same
+       * view of this entry: present or not, and with what content. That is what
+       * makes the draft this produces and the files a publish writes agree -
+       * two expansions of one rule would not.
+       */
+      let ops = [rawOp];
+      if (serializedSchema && isJsonValuesRootOp(serializedSchema, rawOp)) {
+        const write = expandJsonValuesRootOpForKey(rawOp, entryKey, new Map(content === undefined ? [] : [[entryKey, content]]));
+        if (result.isErr(write)) {
+          return {
+            kind: "error",
+            message: write.error.message,
+            patchId
+          };
+        }
+        ops = write.value === null ? [] : [write.value];
       }
-      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.
+      for (const op of ops) {
+        const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+          kind: "normal"
+        };
+        if (cls.kind !== "entry" || cls.recordPath.length > 0 || cls.entryKey !== entryKey) {
           continue;
         }
-        const applied = applyPatch(deepClone(content), jsonOps$2, [{
-          op: "add",
-          path: cls.subPath.concat(...(op.nestedFilePath ?? [])).concat("patch_id"),
-          value: patchId
-        }]);
-        if (result.isErr(applied)) {
+        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$2, [{
+            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;
+            deleted = false;
+          } else if (op.op === "remove") {
+            content = undefined;
+            deleted = true;
+          } else if (op.op === "test") {
+            // An assertion, not a mutation: the content is unchanged either way, and
+            // the commit path is where a failing `test` is reported. Falling through
+            // to the move/copy error below turned a no-op into a permanent load
+            // failure for the whole entry.
+            continue;
+          } else {
+            // move/copy INTO this key: the content comes from the source entry,
+            // which the caller must resolve (it is a different `*.val.json`).
+            return {
+              kind: "error",
+              message: `Cannot resolve '${op.op}' of jsonValues entry '${entryKey}' from its own content`,
+              patchId
+            };
+          }
+          continue;
+        }
+        if (content === undefined) {
           return {
             kind: "error",
-            message: applied.error.message,
+            message: `Cannot edit jsonValues entry '${entryKey}': it does not exist`,
             patchId
           };
         }
-        content = applied.value;
-        continue;
-      }
-      if (cls.subPath.length === 0) {
-        if (op.op === "add" || op.op === "replace") {
-          content = op.value;
-          deleted = false;
-        } else if (op.op === "remove") {
-          content = undefined;
-          deleted = true;
-        } else if (op.op === "test") {
-          // An assertion, not a mutation: the content is unchanged either way, and
-          // the commit path is where a failing `test` is reported. Falling through
-          // to the move/copy error below turned a no-op into a permanent load
-          // failure for the whole entry.
-          continue;
-        } else {
-          // move/copy INTO this key: the content comes from the source entry,
-          // which the caller must resolve (it is a different `*.val.json`).
+        const rebased = rebaseContentOp(op, cls.recordPath.length + 1);
+        if (result.isErr(rebased)) {
           return {
             kind: "error",
-            message: `Cannot resolve '${op.op}' of jsonValues entry '${entryKey}' from its own content`,
+            message: rebased.error.message,
             patchId
           };
         }
-        continue;
-      }
-      if (content === undefined) {
-        return {
-          kind: "error",
-          message: `Cannot edit jsonValues entry '${entryKey}': it does not exist`,
-          patchId
-        };
-      }
-      const rebased = rebaseContentOp(op, cls.recordPath.length + 1);
-      if (result.isErr(rebased)) {
-        return {
-          kind: "error",
-          message: rebased.error.message,
-          patchId
-        };
-      }
-      const applied = applyPatch(deepClone(content), jsonOps$2, [rebased.value]);
-      if (result.isErr(applied)) {
-        return {
-          kind: "error",
-          message: applied.error.message,
-          patchId
-        };
+        const applied = applyPatch(deepClone(content), jsonOps$2, [rebased.value]);
+        if (result.isErr(applied)) {
+          return {
+            kind: "error",
+            message: applied.error.message,
+            patchId
+          };
+        }
+        content = applied.value;
       }
-      content = applied.value;
     }
     if (touched) {
       appliedPatchIds.push(patchId);
@@ -1568,6 +1760,34 @@ function analyzeJsonValuesEntries(source) {
   }
   return entries;
 }
+
+/**
+ * Every key of a `.jsonValues()` record's source literal, thunked or not.
+ *
+ * {@link analyzeJsonValuesEntries} answers "which entries have a file behind
+ * them", which is the question for resolving a path. This is the other one:
+ * which keys the record HAS. They differ on a value that is not a
+ * `c.json(...)` call - written inline, or mid-edit - and telling an existing
+ * key from a new one is what decides whether a whole-record write adds a
+ * `c.json(...)` thunk or replaces one. Using the thunk set for that would
+ * insert a second property with a key the literal already has.
+ */
+function jsonValuesRecordKeys(source) {
+  const keys = [];
+  if (!ts.isObjectLiteralExpression(source)) {
+    return keys;
+  }
+  for (const prop of source.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue;
+    }
+    const key = getPropertyKey(prop.name);
+    if (key !== null) {
+      keys.push(key);
+    }
+  }
+  return keys;
+}
 function getPropertyKey(name) {
   if (ts.isStringLiteralLike(name)) {
     return name.text;
@@ -1874,6 +2094,21 @@ class Service {
       kind: "normal"
     };
     for (const op of patch) {
+      /*
+       * A write of the WHOLE record is refused here, not applied.
+       *
+       * `classifyJsonValuesOp` reads a root path as `normal` - there is no
+       * segment naming an entry - so it would go straight into the `.val.ts`,
+       * replacing the record and the `c.json(() => import(...))` calls that
+       * make its entries load. `ValOps.prepare` expands such a write into
+       * per-entry ops; that needs each entry's file read and written, which
+       * `patchValFile` below does not do. Nothing that reaches here produces
+       * one today (`val validate --fix` only corrects values inside an entry),
+       * so this refuses rather than silently doing the wrong thing.
+       */
+      if (serializedSchema && isJsonValuesRootOp(serializedSchema, op)) {
+        throw Error(`Cannot ${op.op} the whole .jsonValues() record of ${moduleFilePath} through Service.patch: its entries are separate files, so write them per entry`);
+      }
       const cls = classify(op.path);
       // `move` and `copy` read a SECOND path, and `rebaseContentOp` slices
       // `from` by the same prefix it slices `path` by. So an op whose two ends
@@ -2314,6 +2549,15 @@ function encodeJwt(payload, sessionKey) {
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
 const jsonOps = new JSONOps();
+/**
+ * How many `.jsonValues()` entry files a whole-record write reads at a time.
+ *
+ * Reading them is a network round trip per entry in `ValOpsHttp`, and a commit
+ * cannot start until they are in. One at a time is too slow for the records
+ * this is for; all at once is a burst of hundreds of requests at the content
+ * host.
+ */
+const JSON_ENTRY_READ_CONCURRENCY = 8;
 const tsOps = new TSOps(document => {
   return pipe(analyzeValModule(document), result.map(({
     source
@@ -3025,74 +3269,139 @@ class ValOps {
         // poisoning the rest of this module's patch chain). See the per-op
         // routing below.
         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)
-              // to fetch the right file
-              // NOTE: overwrite and use last patch_id if multiple patches modify the same file
-              fileFixOps[op.path.join("/")] = [{
-                op: "add",
-                path: op.path.concat(...(op.nestedFilePath || [])).concat("patch_id"),
-                value: patchId
-              }];
+        /**
+         * The record's keys as they stand while this patch is walked.
+         *
+         * Only the key set: the module source holds markers, so there is no
+         * content here to compare a whole-record write against. Seeded from the
+         * source and kept current as the ops below add and remove entries,
+         * because `patchedSources` is only written once the whole patch has
+         * been applied.
+         */
+        let entryKeys = null;
+        const currentEntryKeys = () => {
+          if (entryKeys === null) {
+            entryKeys = new Map();
+            const source = patchedSources[path];
+            if (typeof source === "object" && source !== null && !Array.isArray(source)) {
+              for (const key of Object.keys(source)) {
+                entryKeys.set(key, undefined);
+              }
             }
-            // null value = delete: no patch_id to inject; the "remove" op in
-            // the patch already removes the metadata entry from the source
-          } else {
-            const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
-              kind: "normal"
-            };
-            if (cls.kind === "normal") {
-              applicableOps.push(op);
-            } else if (cls.subPath.length > 0) ; else if (op.op === "add" || op.op === "replace") {
-              // Whole-entry add/replace: keep the record's KEY SET correct for
-              // drafts by writing the marker rather than the content. Record
-              // validation only asserts `isJson`, and
-              // `validateJsonValuesEntries` skips thunkless markers by design.
-              applicableOps.push({
-                op: op.op,
-                path: op.path,
-                value: {
-                  [VAL_EXTENSION]: "json",
-                  patch_id: patchId
-                }
+          }
+          return entryKeys;
+        };
+        /**
+         * Set when a whole-record write could not be expanded.
+         *
+         * Nothing of this patch is applied then: the ops before the failure are
+         * half of an edit, and half of a record write is a record missing
+         * entries.
+         */
+        let unexpandable = false;
+        for (const rawOp of patchData.patch) {
+          /**
+           * A write of the WHOLE record fans out into per-entry ops first,
+           * through the same expansion the commit flow and the entry read path
+           * use. Left as it is, a root write would put the value straight into
+           * the module source - where the entries are markers, so the record
+           * would hold content the Studio then tries to load as entries.
+           */
+          let ops = [rawOp];
+          if (serializedSchema && isJsonValuesRootOp(serializedSchema, rawOp)) {
+            const expandedRes = expandJsonValuesRootOp(rawOp, currentEntryKeys());
+            if (result.isErr(expandedRes)) {
+              if (!errors[path]) {
+                errors[path] = [];
+              }
+              errors[path].push({
+                patchId,
+                skipped: false,
+                error: expandedRes.error
               });
-            } else if (op.op === "remove") {
-              applicableOps.push(op);
+              unexpandable = true;
+              break;
+            }
+            ops = expandedRes.value;
+          }
+          for (const op of ops) {
+            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)
+                // to fetch the right file
+                // NOTE: overwrite and use last patch_id if multiple patches modify the same file
+                fileFixOps[op.path.join("/")] = [{
+                  op: "add",
+                  path: op.path.concat(...(op.nestedFilePath || [])).concat("patch_id"),
+                  value: patchId
+                }];
+              }
+              // null value = delete: no patch_id to inject; the "remove" op in
+              // the patch already removes the metadata entry from the source
             } else {
-              // move/copy of a whole entry: the destination key must appear, and
-              // for a move the source key must disappear. Both are key-set
-              // changes we can express with markers.
-              applicableOps.push({
-                op: "add",
-                path: op.path,
-                value: {
-                  [VAL_EXTENSION]: "json",
-                  patch_id: patchId
-                }
-              });
-              if (op.op === "move" && array.isNonEmpty(op.from)) {
+              const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+                kind: "normal"
+              };
+              if (cls.kind === "normal") {
+                applicableOps.push(op);
+              } else if (cls.subPath.length > 0) ; else if (op.op === "add" || op.op === "replace") {
+                // Whole-entry add/replace: keep the record's KEY SET correct for
+                // drafts by writing the marker rather than the content. Record
+                // validation only asserts `isJson`, and
+                // `validateJsonValuesEntries` skips thunkless markers by design.
                 applicableOps.push({
-                  op: "remove",
-                  path: op.from
+                  op: op.op,
+                  path: op.path,
+                  value: {
+                    [VAL_EXTENSION]: "json",
+                    patch_id: patchId
+                  }
+                });
+                currentEntryKeys().set(cls.entryKey, undefined);
+              } else if (op.op === "remove") {
+                applicableOps.push(op);
+                currentEntryKeys().delete(cls.entryKey);
+              } else {
+                // move/copy of a whole entry: the destination key must appear, and
+                // for a move the source key must disappear. Both are key-set
+                // changes we can express with markers.
+                applicableOps.push({
+                  op: "add",
+                  path: op.path,
+                  value: {
+                    [VAL_EXTENSION]: "json",
+                    patch_id: patchId
+                  }
                 });
+                currentEntryKeys().set(cls.entryKey, undefined);
+                if (op.op === "move" && array.isNonEmpty(op.from)) {
+                  applicableOps.push({
+                    op: "remove",
+                    path: op.from
+                  });
+                  if (op.from.length === 1) {
+                    currentEntryKeys().delete(op.from[0]);
+                  }
+                }
               }
             }
           }
         }
+        if (unexpandable) {
+          continue;
+        }
         const patchRes = applyPatch(deepClone(patchedSources[path]),
         // applyPatch mutates the source. On add operations it adds more than once? There is something strange going on... deepClone seems to fix, but is that the right solution?
         jsonOps, applicableOps.concat(...Object.values(fileFixOps)));
@@ -3505,22 +3814,34 @@ class ValOps {
       // content ops in the same commit resolve to the freshly-created file.
       const entryKeyToJsonPath = new Map();
 
-      // Lazily analyzed `c.json(() => import("..."))` entries of the ORIGINAL
-      // `.val.ts` (import paths are authoritative for existing/hand-placed files).
-      let analyzerEntries = null;
+      // Lazily analyzed entries of the ORIGINAL `.val.ts`: the
+      // `c.json(() => import("..."))` thunks (import paths are authoritative
+      // for existing/hand-placed files) and the record's whole key set, which
+      // is what a write of the whole record is expanded against.
+      let analyzed = null;
+      const analyzeEntries = () => {
+        if (analyzed === null) {
+          const analysis = analyzeValModule(originalSourceFile);
+          if (result.isErr(analysis)) {
+            return result.err(analysis.error);
+          }
+          analyzed = {
+            thunks: analyzeJsonValuesEntries(analysis.value.source),
+            keys: jsonValuesRecordKeys(analysis.value.source)
+          };
+        }
+        return result.ok(analyzed);
+      };
       const resolveEntryJsonPath = entryKey => {
         const added = entryKeyToJsonPath.get(entryKey);
         if (added !== undefined) {
           return result.ok(added);
         }
-        if (analyzerEntries === null) {
-          const analysis = analyzeValModule(originalSourceFile);
-          if (result.isErr(analysis)) {
-            return result.err(analysis.error);
-          }
-          analyzerEntries = analyzeJsonValuesEntries(analysis.value.source);
+        const analyzedRes = analyzeEntries();
+        if (result.isErr(analyzedRes)) {
+          return analyzedRes;
         }
-        const entry = analyzerEntries.get(entryKey);
+        const entry = analyzedRes.value.thunks.get(entryKey);
         if (!entry) {
           return result.err({
             message: `Could not find jsonValues entry '${entryKey}' in ${path}`,
@@ -3558,6 +3879,73 @@ class ValOps {
           });
         }
       };
+      /**
+       * Every entry the module has AS THINGS STAND, with its content.
+       *
+       * What {@link expandJsonValuesRootOp} expands a write of the whole record
+       * against. The keys come from the `.val.ts` the commit started from plus
+       * what this commit has already added or removed; the content comes from
+       * each entry's file, so an entry the write leaves as it is gets no op and
+       * its file is not rewritten.
+       *
+       * Content is read WITHOUT going through `loadEntryContent`, whose cache is
+       * also the write set: everything in it is written back at the flush, so
+       * reading 200 entries to compare them would rewrite all 200. Unreadable
+       * here means "content unknown", not an error - the expansion then emits a
+       * `replace`, which is what a module with a broken entry file needs anyway.
+       */
+      const currentJsonEntries = async () => {
+        const analyzedRes = analyzeEntries();
+        if (result.isErr(analyzedRes)) {
+          return analyzedRes;
+        }
+        const keys = new Set(analyzedRes.value.keys);
+        for (const [entryKey, content] of jsonEntryContentsByKey) {
+          if (content === null) {
+            keys.delete(entryKey);
+          } else {
+            keys.add(entryKey);
+          }
+        }
+        const readEntry = async entryKey => {
+          const pending = jsonEntryContentsByKey.get(entryKey);
+          if (pending !== undefined && pending !== null) {
+            return pending;
+          }
+          const jsonPathRes = resolveEntryJsonPath(entryKey);
+          if (result.isErr(jsonPathRes)) {
+            return undefined;
+          }
+          const res = await this.getSourceFile(jsonPathRes.value);
+          if (res.error) {
+            return undefined;
+          }
+          try {
+            const parsed = JSON.parse(res.data);
+            return parsed;
+          } catch {
+            return undefined;
+          }
+        };
+        /*
+         * Read in batches rather than one after another: `getSourceFile` is a
+         * network round trip in `ValOpsHttp`, so a record with hundreds of
+         * entries would otherwise spend hundreds of them in series before the
+         * commit could even start - long enough to time out. The keys are
+         * walked in order and the results assembled in that order, so what the
+         * expansion sees does not depend on which read finished first.
+         */
+        const entries = new Map();
+        const entryKeys = Array.from(keys);
+        for (let i = 0; i < entryKeys.length; i += JSON_ENTRY_READ_CONCURRENCY) {
+          const batch = entryKeys.slice(i, i + JSON_ENTRY_READ_CONCURRENCY);
+          const read = await Promise.all(batch.map(readEntry));
+          for (let j = 0; j < batch.length; j++) {
+            entries.set(batch[j], read[j]);
+          }
+        }
+        return result.ok(entries);
+      };
       const collectPatchError = (err, patchId, op) => {
         console.error("Could not patch", JSON.stringify({
           path,
@@ -3598,212 +3986,248 @@ class ValOps {
         // Where this patch's errors start, so the unappliable-patch report below
         // can name what went wrong rather than just that something did.
         const errorsBefore = errors.length;
-        for (const op of sourceFileOps) {
-          const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
-            kind: "normal"
-          };
-          // `move` / `copy` also READ from a path: classify that too, so an op
-          // that moves a value out of (or into) a jsonValues entry cannot slip
-          // through as a plain `.val.ts` op.
-          const fromCls = serializedSchema && (op.op === "move" || op.op === "copy") ? classifyJsonValuesOp(serializedSchema, op.from) : {
-            kind: "normal"
-          };
-          if (cls.kind === "normal" && fromCls.kind === "normal") {
-            const patchRes = applyPatch(tsSourceFile, tsOps, [op]);
-            if (result.isErr(patchRes)) {
-              collectPatchError(patchRes.error, patchId, op);
+        for (const rawOp of sourceFileOps) {
+          /**
+           * A write of the WHOLE record fans out into per-entry ops first.
+           *
+           * The only op `classifyJsonValuesOp` cannot route, because it finds
+           * the entry key by walking the op path and the root path has none. So
+           * a patch author never has to know whether a record is
+           * `.jsonValues()`: they write the module as if it were ordinary
+           * source, and it arrives here as adds, replaces and removes that name
+           * a key - the shapes everything below already handles. The read side
+           * expands through the same function, so a draft cannot show something
+           * other than what this writes.
+           */
+          let ops = [rawOp];
+          if (serializedSchema && isJsonValuesRootOp(serializedSchema, rawOp)) {
+            const currentRes = await currentJsonEntries();
+            if (result.isErr(currentRes)) {
+              errors.push(currentRes.error);
               patchHadError = true;
               break;
             }
-            tsSourceFile = patchRes.value;
-            tsChanged = true;
-            continue;
-          }
-          if (cls.kind === "normal") {
-            errors.push({
-              message: `Cannot '${op.op}' a value out of a jsonValues entry and into the module source`,
-              filePath: path
-            });
-            patchHadError = true;
-            break;
-          }
-          // Nested `.jsonValues()` records are not supported: only the read path
-          // for a module's ROOT record/router is implemented end to end. This is
-          // also rejected up front in `initSources`; this is defense in depth.
-          if (cls.recordPath.length > 0 || fromCls.kind === "entry" && fromCls.recordPath.length > 0) {
-            errors.push({
-              message: `Nested .jsonValues() records are not supported: '${cls.recordPath.join(".")}' in ${path}. Use .jsonValues() only on a module's root record/router.`,
-              filePath: path
-            });
-            patchHadError = true;
-            break;
+            const expandedRes = expandJsonValuesRootOp(rawOp, currentRes.value);
+            if (result.isErr(expandedRes)) {
+              errors.push({
+                message: expandedRes.error.message,
+                filePath: path
+              });
+              patchHadError = true;
+              break;
+            }
+            ops = expandedRes.value;
           }
-          // The op targets a `.jsonValues()` entry.
-          if (cls.subPath.length === 0) {
-            // Structural / whole-entry op.
-            if (op.op === "add") {
-              const newPathsRes = getNewJsonEntryPaths(path, cls.entryKey);
-              if (result.isErr(newPathsRes)) {
-                errors.push(newPathsRes.error);
-                patchHadError = true;
-                break;
-              }
-              const {
-                jsonPath,
-                importPath
-              } = newPathsRes.value;
-              const insRes = insertValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey, importPath);
-              if (result.isErr(insRes)) {
-                collectPatchError(insRes.error, patchId, op);
-                patchHadError = true;
-                break;
-              }
-              tsSourceFile = insRes.value;
-              tsChanged = true;
-              jsonEntryContents.set(jsonPath, op.value);
-              jsonEntryContentsByKey.set(cls.entryKey, op.value);
-              entryKeyToJsonPath.set(cls.entryKey, jsonPath);
-            } else if (op.op === "remove") {
-              const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
-              if (result.isErr(jsonPathRes)) {
-                errors.push(jsonPathRes.error);
-                patchHadError = true;
-                break;
-              }
-              const remRes = removeValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey);
-              if (result.isErr(remRes)) {
-                collectPatchError(remRes.error, patchId, op);
+          for (const op of ops) {
+            const cls = serializedSchema ? classifyJsonValuesOp(serializedSchema, op.path) : {
+              kind: "normal"
+            };
+            // `move` / `copy` also READ from a path: classify that too, so an op
+            // that moves a value out of (or into) a jsonValues entry cannot slip
+            // through as a plain `.val.ts` op.
+            const fromCls = serializedSchema && (op.op === "move" || op.op === "copy") ? classifyJsonValuesOp(serializedSchema, op.from) : {
+              kind: "normal"
+            };
+            if (cls.kind === "normal" && fromCls.kind === "normal") {
+              const patchRes = applyPatch(tsSourceFile, tsOps, [op]);
+              if (result.isErr(patchRes)) {
+                collectPatchError(patchRes.error, patchId, op);
                 patchHadError = true;
                 break;
               }
-              tsSourceFile = remRes.value;
+              tsSourceFile = patchRes.value;
               tsChanged = true;
-              jsonEntryContents.set(jsonPathRes.value, null);
-              jsonEntryContentsByKey.set(cls.entryKey, null);
-            } else if (op.op === "replace") {
-              const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
-              if (result.isErr(jsonPathRes)) {
-                errors.push(jsonPathRes.error);
+              continue;
+            }
+            if (cls.kind === "normal") {
+              errors.push({
+                message: `Cannot '${op.op}' a value out of a jsonValues entry and into the module source`,
+                filePath: path
+              });
+              patchHadError = true;
+              break;
+            }
+            // Nested `.jsonValues()` records are not supported: only the read path
+            // for a module's ROOT record/router is implemented end to end. This is
+            // also rejected up front in `initSources`; this is defense in depth.
+            if (cls.recordPath.length > 0 || fromCls.kind === "entry" && fromCls.recordPath.length > 0) {
+              errors.push({
+                message: `Nested .jsonValues() records are not supported: '${cls.recordPath.join(".")}' in ${path}. Use .jsonValues() only on a module's root record/router.`,
+                filePath: path
+              });
+              patchHadError = true;
+              break;
+            }
+            // The op targets a `.jsonValues()` entry.
+            if (cls.subPath.length === 0) {
+              // Structural / whole-entry op.
+              if (op.op === "add") {
+                const newPathsRes = getNewJsonEntryPaths(path, cls.entryKey);
+                if (result.isErr(newPathsRes)) {
+                  errors.push(newPathsRes.error);
+                  patchHadError = true;
+                  break;
+                }
+                const {
+                  jsonPath,
+                  importPath
+                } = newPathsRes.value;
+                const insRes = insertValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey, importPath);
+                if (result.isErr(insRes)) {
+                  collectPatchError(insRes.error, patchId, op);
+                  patchHadError = true;
+                  break;
+                }
+                tsSourceFile = insRes.value;
+                tsChanged = true;
+                jsonEntryContents.set(jsonPath, op.value);
+                jsonEntryContentsByKey.set(cls.entryKey, op.value);
+                entryKeyToJsonPath.set(cls.entryKey, jsonPath);
+              } else if (op.op === "remove") {
+                const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
+                if (result.isErr(jsonPathRes)) {
+                  errors.push(jsonPathRes.error);
+                  patchHadError = true;
+                  break;
+                }
+                const remRes = removeValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey);
+                if (result.isErr(remRes)) {
+                  collectPatchError(remRes.error, patchId, op);
+                  patchHadError = true;
+                  break;
+                }
+                tsSourceFile = remRes.value;
+                tsChanged = true;
+                jsonEntryContents.set(jsonPathRes.value, null);
+                jsonEntryContentsByKey.set(cls.entryKey, null);
+              } else if (op.op === "replace") {
+                const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
+                if (result.isErr(jsonPathRes)) {
+                  errors.push(jsonPathRes.error);
+                  patchHadError = true;
+                  break;
+                }
+                jsonEntryContents.set(jsonPathRes.value, op.value);
+                jsonEntryContentsByKey.set(cls.entryKey, op.value);
+              } else if (op.op === "move" || op.op === "copy") {
+                // Rename (move) or duplicate (copy) a whole entry. The new entry
+                // gets its own `*.val.json` written with the source entry's
+                // content plus a `c.json(...)` thunk; a move additionally drops
+                // the old thunk and deletes the old file.
+                if (fromCls.kind !== "entry" || fromCls.subPath.length !== 0 || fromCls.recordPath.join("\0") !== cls.recordPath.join("\0")) {
+                  errors.push({
+                    message: `Cannot '${op.op}' a jsonValues entry across records or from a non-entry path (from '${op.from.join(".")}' to '${op.path.join(".")}')`,
+                    filePath: path
+                  });
+                  patchHadError = true;
+                  break;
+                }
+                const fromKey = fromCls.entryKey;
+                const fromPathRes = resolveEntryJsonPath(fromKey);
+                if (result.isErr(fromPathRes)) {
+                  errors.push(fromPathRes.error);
+                  patchHadError = true;
+                  break;
+                }
+                // Load BEFORE marking anything deleted: `loadEntryContent` errors
+                // on a path that has already been nulled in this commit.
+                const contentRes = await loadEntryContent(fromPathRes.value);
+                if (result.isErr(contentRes)) {
+                  errors.push(contentRes.error);
+                  patchHadError = true;
+                  break;
+                }
+                const content = deepClone(contentRes.value);
+                if (op.op === "move") {
+                  const remRes = removeValJsonEntry(tsSourceFile, cls.recordPath, fromKey);
+                  if (result.isErr(remRes)) {
+                    collectPatchError(remRes.error, patchId, op);
+                    patchHadError = true;
+                    break;
+                  }
+                  tsSourceFile = remRes.value;
+                }
+                // LOCKED convention: the destination always uses the generated
+                // path, so renaming a hand-placed file relocates it.
+                const newPathsRes = getNewJsonEntryPaths(path, cls.entryKey);
+                if (result.isErr(newPathsRes)) {
+                  errors.push(newPathsRes.error);
+                  patchHadError = true;
+                  break;
+                }
+                const {
+                  jsonPath,
+                  importPath
+                } = newPathsRes.value;
+                const insRes = insertValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey, importPath);
+                if (result.isErr(insRes)) {
+                  collectPatchError(insRes.error, patchId, op);
+                  patchHadError = true;
+                  break;
+                }
+                tsSourceFile = insRes.value;
+                tsChanged = true;
+                jsonEntryContents.set(jsonPath, content);
+                jsonEntryContentsByKey.set(cls.entryKey, content);
+                entryKeyToJsonPath.set(cls.entryKey, jsonPath);
+                if (op.op === "move" && fromPathRes.value !== jsonPath) {
+                  jsonEntryContents.set(fromPathRes.value, null);
+                  jsonEntryContentsByKey.set(fromKey, null);
+                }
+              } else {
+                errors.push({
+                  message: `Unsupported op '${op.op}' on jsonValues entry '${cls.entryKey}' (supported: add, remove, replace, move, copy)`,
+                  filePath: path
+                });
                 patchHadError = true;
                 break;
               }
-              jsonEntryContents.set(jsonPathRes.value, op.value);
-              jsonEntryContentsByKey.set(cls.entryKey, op.value);
-            } else if (op.op === "move" || op.op === "copy") {
-              // Rename (move) or duplicate (copy) a whole entry. The new entry
-              // gets its own `*.val.json` written with the source entry's
-              // content plus a `c.json(...)` thunk; a move additionally drops
-              // the old thunk and deletes the old file.
-              if (fromCls.kind !== "entry" || fromCls.subPath.length !== 0 || fromCls.recordPath.join("\0") !== cls.recordPath.join("\0")) {
+            } else {
+              // Content sub-op: replay against the entry's `*.val.json`.
+              // `rebaseContentOp` slices `from` by the same prefix as `path`, so a
+              // cross-entry move/copy would silently corrupt the target entry.
+              if ((op.op === "move" || op.op === "copy") && (fromCls.kind !== "entry" || fromCls.entryKey !== cls.entryKey)) {
                 errors.push({
-                  message: `Cannot '${op.op}' a jsonValues entry across records or from a non-entry path (from '${op.from.join(".")}' to '${op.path.join(".")}')`,
+                  message: `Cannot '${op.op}' between different jsonValues entries`,
                   filePath: path
                 });
                 patchHadError = true;
                 break;
               }
-              const fromKey = fromCls.entryKey;
-              const fromPathRes = resolveEntryJsonPath(fromKey);
-              if (result.isErr(fromPathRes)) {
-                errors.push(fromPathRes.error);
+              const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
+              if (result.isErr(jsonPathRes)) {
+                errors.push(jsonPathRes.error);
                 patchHadError = true;
                 break;
               }
-              // Load BEFORE marking anything deleted: `loadEntryContent` errors
-              // on a path that has already been nulled in this commit.
-              const contentRes = await loadEntryContent(fromPathRes.value);
+              const jsonPath = jsonPathRes.value;
+              const contentRes = await loadEntryContent(jsonPath);
               if (result.isErr(contentRes)) {
                 errors.push(contentRes.error);
                 patchHadError = true;
                 break;
               }
-              const content = deepClone(contentRes.value);
-              if (op.op === "move") {
-                const remRes = removeValJsonEntry(tsSourceFile, cls.recordPath, fromKey);
-                if (result.isErr(remRes)) {
-                  collectPatchError(remRes.error, patchId, op);
-                  patchHadError = true;
-                  break;
-                }
-                tsSourceFile = remRes.value;
-              }
-              // LOCKED convention: the destination always uses the generated
-              // path, so renaming a hand-placed file relocates it.
-              const newPathsRes = getNewJsonEntryPaths(path, cls.entryKey);
-              if (result.isErr(newPathsRes)) {
-                errors.push(newPathsRes.error);
+              const rebasedRes = rebaseContentOp(op, cls.recordPath.length + 1);
+              if (result.isErr(rebasedRes)) {
+                errors.push({
+                  message: rebasedRes.error.message,
+                  filePath: jsonPath
+                });
                 patchHadError = true;
                 break;
               }
-              const {
-                jsonPath,
-                importPath
-              } = newPathsRes.value;
-              const insRes = insertValJsonEntry(tsSourceFile, cls.recordPath, cls.entryKey, importPath);
-              if (result.isErr(insRes)) {
-                collectPatchError(insRes.error, patchId, op);
+              const applied = applyPatch(deepClone(contentRes.value), jsonOps, [rebasedRes.value]);
+              if (result.isErr(applied)) {
+                collectPatchError(applied.error, patchId, op);
                 patchHadError = true;
                 break;
               }
-              tsSourceFile = insRes.value;
-              tsChanged = true;
-              jsonEntryContents.set(jsonPath, content);
-              jsonEntryContentsByKey.set(cls.entryKey, content);
-              entryKeyToJsonPath.set(cls.entryKey, jsonPath);
-              if (op.op === "move" && fromPathRes.value !== jsonPath) {
-                jsonEntryContents.set(fromPathRes.value, null);
-                jsonEntryContentsByKey.set(fromKey, null);
-              }
-            } else {
-              errors.push({
-                message: `Unsupported op '${op.op}' on jsonValues entry '${cls.entryKey}' (supported: add, remove, replace, move, copy)`,
-                filePath: path
-              });
-              patchHadError = true;
-              break;
-            }
-          } else {
-            // Content sub-op: replay against the entry's `*.val.json`.
-            // `rebaseContentOp` slices `from` by the same prefix as `path`, so a
-            // cross-entry move/copy would silently corrupt the target entry.
-            if ((op.op === "move" || op.op === "copy") && (fromCls.kind !== "entry" || fromCls.entryKey !== cls.entryKey)) {
-              errors.push({
-                message: `Cannot '${op.op}' between different jsonValues entries`,
-                filePath: path
-              });
-              patchHadError = true;
-              break;
-            }
-            const jsonPathRes = resolveEntryJsonPath(cls.entryKey);
-            if (result.isErr(jsonPathRes)) {
-              errors.push(jsonPathRes.error);
-              patchHadError = true;
-              break;
-            }
-            const jsonPath = jsonPathRes.value;
-            const contentRes = await loadEntryContent(jsonPath);
-            if (result.isErr(contentRes)) {
-              errors.push(contentRes.error);
-              patchHadError = true;
-              break;
+              jsonEntryContents.set(jsonPath, applied.value);
+              jsonEntryContentsByKey.set(cls.entryKey, applied.value);
             }
-            const rebasedRes = rebaseContentOp(op, cls.recordPath.length + 1);
-            if (result.isErr(rebasedRes)) {
-              errors.push({
-                message: rebasedRes.error.message,
-                filePath: jsonPath
-              });
-              patchHadError = true;
-              break;
-            }
-            const applied = applyPatch(deepClone(contentRes.value), jsonOps, [rebasedRes.value]);
-            if (result.isErr(applied)) {
-              collectPatchError(applied.error, patchId, op);
-              patchHadError = true;
-              break;
-            }
-            jsonEntryContents.set(jsonPath, applied.value);
-            jsonEntryContentsByKey.set(cls.entryKey, applied.value);
+          }
+          if (patchHadError) {
+            break;
           }
         }
         if (patchHadError) {
@@ -7136,6 +7560,18 @@ const SavePatchFileResponse = z.object({
 const CommitResponse = z.object({
   updatedFiles: z.array(z.string()),
   commit: CommitSha,
+  /*
+   * Optional because a content service that predates them sends neither, and
+   * this client talks to whichever one the project is on. Absent means NOT
+   * REPORTED: `parent: undefined` is not "a root commit", and a caller that
+   * reads it as one would conclude the history starts here.
+   *
+   * Unbranded strings deliberately -- see `CommitResult.parent`. They arrive
+   * from a service that versions separately and are passed through as what it
+   * said, not as something this end vouched for.
+   */
+  parent: z.string().optional(),
+  tree: z.string().optional(),
   branch: z.string()
 });
 // #region history wire schemas
@@ -8463,7 +8899,19 @@ class ValOpsHttp extends ValOps {
           return {
             updatedFiles: parsed.data.updatedFiles,
             commit: parsed.data.commit,
-            branch: parsed.data.branch
+            branch: parsed.data.branch,
+            /*
+             * Spread rather than set, so a service that did not report them
+             * leaves the keys ABSENT rather than present-and-undefined. A
+             * caller doing `'parent' in result` then gets the truthful answer,
+             * and JSON round-trips of this object do not grow null fields.
+             */
+            ...(parsed.data.parent !== undefined ? {
+              parent: parsed.data.parent
+            } : {}),
+            ...(parsed.data.tree !== undefined ? {
+              tree: parsed.data.tree
+            } : {})
           };
         }
         return {
@@ -10017,6 +10465,67 @@ function parsePersonalAccessTokenFile(content) {
 
 const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
 
+/**
+ * The value of `VAL_ENV` that means "this is the Val app".
+ *
+ * The Val app builds a project in a browser and runs it in a Worker isolate.
+ * There is no disk there and there never will be, so `fs` mode is never the
+ * right fall-through -- and the content is Val's own, reached over HTTP at a
+ * commit, exactly as it is for any other deployed app. So this names `http`.
+ *
+ * What makes the app unusual is not where its content comes from but what
+ * publishing means: the browser rebuilds the site and the new build is served
+ * immediately, instead of a host noticing a commit and redeploying. That is a
+ * difference in what happens AFTER the commit, and `publishOverride` is where
+ * a host says so -- not a difference in where patches, files or sources live.
+ *
+ * A host says WHERE it runs, which is a fact it knows. Which Val mode that
+ * implies is Val's to derive, and that is the whole reason this exists next to
+ * `VAL_MODE` rather than the platform naming a mode itself: one is a
+ * description of an environment, the other an assertion about Val's internals,
+ * and only the first stays true when the internals move. They have already
+ * moved once -- this meant `memory` while the app kept its own patch store --
+ * and no platform had to be changed to follow.
+ */
+const VAL_APP_ENV = "app";
+
+/** Which mode the environment SAYS this is, and which variable said so. */
+
+/**
+ * `null` is "the environment did not say", which is the normal case.
+ *
+ * The two variables differ in what can be DONE with an answer, and the
+ * difference is whether the environment holds everything the mode needs.
+ * `http` does -- an api key, a secret, a project, a commit and a branch are all
+ * env vars -- so `VAL_ENV=app` SELECTS it, and the checks in
+ * {@link initHandlerOptions} name whichever one is missing. `memory` does not:
+ * it needs the host's own source files, which nothing in an environment can
+ * supply, so `VAL_MODE=memory` can only ever turn a fall-through into an error.
+ */
+function namedMode() {
+  const declared = process.env.VAL_MODE;
+  /*
+   * An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+   * CI settings page means. An explicit `VAL_MODE` otherwise wins over
+   * `VAL_ENV`: naming a mode outright says something more specific than naming
+   * an environment does, including when what it names is wrong and has to be
+   * refused.
+   */
+  if (declared !== undefined && declared !== "") {
+    return {
+      mode: declared,
+      from: "VAL_MODE"
+    };
+  }
+  if (process.env.VAL_ENV === VAL_APP_ENV) {
+    return {
+      mode: "http",
+      from: "VAL_ENV"
+    };
+  }
+  return null;
+}
+
 /**
  * Resolve options plus environment into a concrete {@link ValServerConfig}.
  *
@@ -10070,11 +10579,13 @@ async function initHandlerOptions(route, opts, config) {
     };
   }
   /*
-   * `VAL_MODE=memory` says the host MEANT to hold the source, and did not.
+   * The environment saying 'memory' means the host MEANT to hold the source,
+   * and did not. Either variable can say it: `VAL_MODE=memory` outright, or
+   * `VAL_ENV=app`, which names an environment that has no disk.
    *
-   * It cannot SELECT memory mode -- nothing in the environment can supply
+   * Neither can SELECT memory mode -- nothing in the environment can supply
    * `sourceFiles`, and a mode turned on without them is a server with no
-   * content in it. What it does is turn the fall-through into an error.
+   * content in it. What they do is turn the fall-through into an error.
    *
    * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
    * mode in a Worker isolate reaches for a working tree that is not there: the
@@ -10083,20 +10594,37 @@ async function initHandlerOptions(route, opts, config) {
    * environment that runs Val without a disk can set this once and get a
    * sentence instead.
    */
-  const declaredMode = process.env.VAL_MODE;
-  if (declaredMode === "memory") {
-    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset " + "VAL_MODE to go back to the inferred mode instead ('http' when " + "VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise).");
+  const declared = namedMode();
+  if ((declared === null || declared === void 0 ? void 0 : declared.mode) === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset VAL_MODE to go back to the inferred mode instead " + "('http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' " + "otherwise).");
   }
-  // An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
-  // CI settings page means. Every other value is refused rather than ignored:
-  // ignoring `VAL_MODE=memry` would leave the app in `fs` mode, which is the
-  // exact failure this variable exists to catch.
-  if (declaredMode !== undefined && declaredMode !== "") {
-    throw new Error(`VAL_MODE is '${declaredMode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  /*
+   * Every other value is refused rather than ignored: ignoring `VAL_MODE=memry`
+   * would leave the app in `fs` mode, which is the exact failure this variable
+   * exists to catch.
+   *
+   * `VAL_ENV` is excluded by name rather than by its value happening to pass:
+   * it names 'http', which is selected below, and a reader who sees only
+   * `declared !== null` here would reasonably conclude that 'http' is a
+   * `VAL_MODE` value -- it is not, and the message below says so.
+   */
+  if (declared !== null && declared.from === "VAL_MODE") {
+    throw new Error(`VAL_MODE is '${declared.mode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
   }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
-  const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);
+  /*
+   * The app's environment selects http mode, rather than leaving it to be
+   * inferred from a credential being present.
+   *
+   * The difference shows when something is MISSING. Inference reads an absent
+   * api key as "not a proxy" and falls through to `fs`, which in an isolate
+   * reaches for a working tree that is not there -- an `EPERM` on
+   * `.val/patches.lock`, several layers below the mistake. Selecting the mode
+   * means the checks below run instead, and each one names what it wanted.
+   */
+  const isAppEnv = (declared === null || declared === void 0 ? void 0 : declared.from) === "VAL_ENV";
+  const isProxyMode = opts.mode === "proxy" || isAppEnv || opts.mode === undefined && (maybeApiKey || maybeValSecret);
   const valEnableRedirectUrl = opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL;
   const valDisableRedirectUrl = opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL;
   const maybeValProject = opts.project || process.env.VAL_PROJECT;
@@ -10108,19 +10636,28 @@ async function initHandlerOptions(route, opts, config) {
   });
   if (isProxyMode) {
     var _opts$versions, _opts$versions2;
+    /*
+     * Why this app is in http mode, in the message that says what is missing.
+     *
+     * "must be set in proxy mode" is a fine sentence for a developer who wrote
+     * `mode: "proxy"` and a poor one for an app that never mentioned a mode:
+     * there, the answer to "why am I in proxy mode?" is a variable set by the
+     * platform, in a file the reader of this error is not looking at.
+     */
+    const because = isAppEnv ? " (VAL_ENV is 'app', which is the Val app: its content is Val's own " + "and is read over HTTP at a commit, so http mode is the mode and " + "these are what it needs)" : "";
     if (!maybeApiKey || !maybeValSecret) {
-      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode");
+      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode" + because);
     }
     const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
     if (!maybeGitCommit) {
-      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode");
+      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode" + because);
     }
     const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
     if (!maybeGitBranch) {
-      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode");
+      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode" + because);
     }
     if (!maybeValProject) {
-      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set.");
+      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set." + because);
     }
     const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
     if (!coreVersion) {