@valbuild/server 0.132.0 → 0.133.0

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;
+              jsonEntryContents.set(jsonPath, applied.value);
+              jsonEntryContentsByKey.set(cls.entryKey, applied.value);
             }
-          } 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;
-            }
-            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) {
@@ -3889,7 +4313,25 @@ class ValOps {
       };
     };
     const patchedJsonEntries = {};
-    const allResults = await Promise.all(Object.entries(patchesByModule).map(([path, patches]) => applySourceFilePatches(path, patches)));
+    /*
+     * Patching the FILE TEXT, for a store that has somewhere to put it.
+     *
+     * Where there is nowhere -- an http project with no repository -- the
+     * patches are still all applied, because they are: `getSources(analysis)`
+     * below applies them to Source, and that is what the commit records and
+     * what every reader of this project sees. What is skipped is rendering
+     * that data back out as `.val.ts` and `*.val.json`, which would be a
+     * mirror with no repository to mirror into -- and which cannot even be
+     * attempted, because producing it starts by READING the current text from
+     * the repository that is not there.
+     */
+    const allResults = await Promise.all(Object.entries(patchesByModule).map(([path, patches]) => this.mirrorsSourceFiles ? applySourceFilePatches(path, patches) : Promise.resolve({
+      path: path,
+      appliedPatches: patches.map(p => p.patchId),
+      result: null,
+      extraFiles: {},
+      jsonEntries: {}
+    })));
     let hasErrors = false;
     const sourceFilePatchErrors = {};
     const appliedPatches = {};
@@ -4064,6 +4506,46 @@ class ValOps {
     });
   }
 
+  /**
+   * Why a publish cannot happen here, or `null` when one can.
+   *
+   * Named rather than thrown, and asked BEFORE the click: the Studio shows the
+   * reason and disables the action, instead of letting someone write a commit
+   * message and then meeting a failure from four layers down.
+   *
+   * `no-base` is the only code so far and means what it says: there is nowhere
+   * for this publish's commit to be based. Note which way round that is --
+   * a project whose content service is the store of record always HAS a base
+   * (the service's own chain, which mints its own shas), so the refusal is not
+   * about missing git. It is about a deployment that cannot do what its
+   * project requires.
+   */
+  publishRefusal() {
+    return null;
+  }
+
+  /**
+   * Whether a commit here produces `.val.ts` TEXT as well as data.
+   *
+   * True everywhere there is somewhere to put it: a working tree in `fs` mode,
+   * a host holding its own source in memory mode, a git repository in `http`
+   * mode. False for an `http` project whose content service is the store of
+   * record and which has no repository attached -- see `git` on
+   * {@link ValApiOptions}.
+   *
+   * WHAT IS NOT AFFECTED, and it is the part worth being sure of:
+   * `moduleVersions` -- what each changed module IS after the commit, with its
+   * schema -- comes from `getSources(analysis)`, which applies the ops to
+   * Source in the stores. It does not go near the file text. So a commit with
+   * no mirror still records everything history and a later `connect-github`
+   * fold need; what it does not record is a rendering of that data as code.
+   *
+   * WHAT IS: the ops are no longer applied to the file text as well, so a
+   * patch that would not fit the `.val.ts` is not reported here. That check
+   * only ever existed for the text being produced, and there is none.
+   */
+  mirrorsSourceFiles = true;
+
   /**
    * Take the `.val.ts` text a commit produced as the new committed source.
    *
@@ -4228,6 +4710,16 @@ function formatPatchSourceError(error) {
     return "Unknown patch source error: " + JSON.stringify(_exhaustiveCheck);
   }
 }
+
+/**
+ * Why a publish is refused, in a form a person can be shown.
+ *
+ * `code` is for the Studio to branch on and `message` is what it says. Both,
+ * rather than a code and a lookup table on the client: the server knows what
+ * is actually missing -- which branch, which commit -- and a client-side table
+ * could only ever say the generic version.
+ */
+
 /**
  * The patches a json entry render should apply, out of the whole chain.
  *
@@ -7067,8 +7559,14 @@ const GetApplicablePatches = z.object({
   })),
   commits: z.array(z.object({
     commitSha: z.string(),
-    clientCommitSha: z.string(),
-    parentCommitSha: z.string(),
+    /*
+     * Nullable since the content service mints its own commit shas: a
+     * root commit has no parent, and a publisher that did not say where
+     * it was has no client sha. Parsed rather than trusted, so a service
+     * that sends null gets null here instead of failing the whole poll.
+     */
+    clientCommitSha: z.string().nullable(),
+    parentCommitSha: z.string().nullable(),
     commitMessage: z.string().nullable(),
     branch: z.string(),
     creator: z.string(),
@@ -7084,7 +7582,21 @@ const GetApplicablePatches = z.object({
     // `ValDeployment`: this is the only source for a deployment that Val
     // did not publish, and zod would otherwise strip it here.
     commitMessage: z.string().nullable().optional()
-  })).optional()
+  })).optional(),
+  /**
+   * What the project EXPECTS of whoever publishes it.
+   *
+   * Optional because a content service that predates it sends nothing, and
+   * absent means "not reported" -- never "managed". The difference decides
+   * whether a publish is refused, so guessing either way would be worse than
+   * not checking: guessing `managed` would let a deployment publish a
+   * connected project it cannot mirror, and guessing `connected` would refuse
+   * every publish against an older service.
+   */
+  project: z.object({
+    sourceMode: z.union([z.literal("managed"), z.literal("connected")]),
+    branch: z.string()
+  }).optional()
 });
 const FilesResponse = z.object({
   files: z.array(z.union([z.object({
@@ -7136,6 +7648,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
@@ -7145,8 +7669,10 @@ const CommitResponse = z.object({
 // commit changed nothing", which is indistinguishable from a real answer.
 const HistoricalCommitResponse = z.object({
   commitSha: z.string(),
-  parentCommitSha: z.string(),
-  clientCommitSha: z.string(),
+  /** `null` for a root commit; see the note on the applicable-patches schema. */
+  parentCommitSha: z.string().nullable(),
+  /** `null` when the publisher did not say where it was. */
+  clientCommitSha: z.string().nullable(),
   branch: z.string(),
   createdBranch: z.string().nullable(),
   creator: z.string().nullable(),
@@ -7164,8 +7690,8 @@ const CommitPatchesResponse = z.object({
   commitSha: z.string(),
   commit: z.object({
     commitSha: z.string(),
-    parentCommitSha: z.string(),
-    clientCommitSha: z.string(),
+    parentCommitSha: z.string().nullable(),
+    clientCommitSha: z.string().nullable(),
     branch: z.string(),
     createdBranch: z.string().nullable(),
     creator: z.string().nullable(),
@@ -7265,9 +7791,45 @@ class ValOpsHttp extends ValOps {
   patchesAreLocal = false;
   /** See {@link ValOps.requiresAuth}. */
   requiresAuth = true;
-  constructor(contentUrl, project, commitSha,
-  // TODO: CommitSha
-  branch,
+  /**
+   * A commit mirrors into `.val.ts` only when there is a repository.
+   *
+   * See {@link ValOps.mirrorsSourceFiles}. Set in the constructor rather than
+   * as an initialiser because it depends on `git`, and a class field
+   * initialiser runs before the constructor body has assigned it.
+   */
+  mirrorsSourceFiles;
+  /**
+   * What the content service last said this project expects of its publisher.
+   *
+   * `null` until something has asked it, which in practice is the first poll.
+   * It is remembered rather than asked for on demand because the answer is
+   * only wanted on the publish path, and that path already fetches the
+   * patches it is publishing -- so a dedicated request would be a second round
+   * trip for two fields that just arrived.
+   *
+   * It can be one poll out of date, and that is the right amount: the thing it
+   * changes is whether this deployment can mirror commits into a repository,
+   * which changes when a project CONNECTS one -- and a project that has just
+   * connected is one whose builds are about to be replaced anyway.
+   */
+  projectExpectation = null;
+  constructor(contentUrl, project,
+  /**
+   * The repository this project's commits are mirrored into, or `null`.
+   *
+   * `null` is a project whose content service is the store of record: it
+   * mints its own commit shas, and it knows this project's branch from the
+   * project itself. Every request below that would have carried a branch and
+   * a commit omits them instead, and the service answers from the project's
+   * own chain -- which is where those answers always came from.
+   *
+   * It is NOT a degraded mode. The one thing that genuinely needs a
+   * repository is producing the `.val.ts` text a commit mirrors, and a
+   * project with no repository has nothing to mirror into. See `git` on
+   * {@link ValApiOptions}.
+   */
+  git,
   /**
    * An api key (how the app itself authenticates) or a personal access token
    * (how the CLI authenticates after `val login`). Same two shapes as
@@ -7277,14 +7839,49 @@ class ValOpsHttp extends ValOps {
     super(valModules, options);
     this.contentUrl = contentUrl;
     this.project = project;
-    this.commitSha = commitSha;
-    this.branch = branch;
+    this.git = git;
     this.authHeaders = "pat" in auth ? {
       "x-val-pat": auth.pat
     } : {
       Authorization: `Bearer ${auth.apiKey}`
     };
     this.root = (options === null || options === void 0 ? void 0 : options.root) ?? "";
+    this.mirrorsSourceFiles = git !== null;
+  }
+  /**
+   * A deployment that cannot mirror a project which expects to be mirrored.
+   *
+   * This is the one shape of "no base" that exists, and it is not the one it
+   * sounds like. A project with no repository is fine: the content service is
+   * the store of record for it and mints its own commit shas, so there is
+   * always somewhere for the commit to go. What is refused is the mismatch --
+   * a project whose commits are mirrored into a repository, being published by
+   * a build that was made before it had one and so has no commit to produce
+   * that mirror against.
+   *
+   * It is a REAL state rather than a defensive check: it is exactly what a
+   * deployment looks like between a project connecting a repository and its
+   * next build going out. Left unchecked, such a publish writes the data and
+   * silently fails to mirror it, and the repository quietly falls behind the
+   * content nobody is told about.
+   *
+   * `null` when the service did not say (see `project` on the response
+   * schema): an older content service is not evidence of anything, and
+   * refusing every publish against one would be a worse failure than not
+   * checking.
+   */
+  publishRefusal() {
+    var _this$projectExpectat;
+    if (this.git !== null) {
+      return null;
+    }
+    if (((_this$projectExpectat = this.projectExpectation) === null || _this$projectExpectat === void 0 ? void 0 : _this$projectExpectat.sourceMode) !== "connected") {
+      return null;
+    }
+    return {
+      code: "no-base",
+      message: `This project mirrors its content into a git repository (branch ` + `'${this.projectExpectation.branch}'), but this deployment was not ` + "built from one, so it does not know which commit to write that " + "mirror against. Publishing would save the content and silently " + "leave the repository behind. Deploy this project again from its " + "repository, and publishing will work from that build on."
+    };
   }
   async onInit() {
     // TODO: unused for now. Implement or remove
@@ -7475,16 +8072,31 @@ class ValOpsHttp extends ValOps {
        * decided against.
        */
       headCommitSha: newestCommitSha(allPatchData.commits) ?? undefined,
-      commitSha: this.commitSha
+      /*
+       * Spread: a project with no repository has no such commit, and saying
+       * so by leaving the key out is different from sending an empty string
+       * the Studio would try to show.
+       */
+      ...(this.git ? {
+        commitSha: this.git.commit
+      } : {})
     };
   }
   async getWebSocketNonce(profileId) {
     return fetch(`${this.contentUrl}/v1/${this.project}/websocket/nonces`, {
       method: "POST",
       body: JSON.stringify({
-        branch: this.branch,
         profileId,
-        commitSha: this.commitSha
+        /*
+         * Omitted when there is no repository, like every other request here.
+         * The content service knows this project's branch -- it is a column on
+         * the project -- and a nonce is scoped to the project and the person,
+         * not to a position in a chain.
+         */
+        ...(this.git ? {
+          branch: this.git.branch,
+          commitSha: this.git.commit
+        } : {})
       }),
       headers: {
         ...this.authHeaders,
@@ -7632,8 +8244,20 @@ class ValOpsHttp extends ValOps {
   }
   async fetchPatchesInternal(filters) {
     const params = [];
-    params.push(["branch", this.branch]);
-    params.push(["commit", this.commitSha]);
+    /*
+     * A position in the chain, WHEN THIS BUILD HAS ONE.
+     *
+     * `commit` tells the content service where this deployment sits, so it can
+     * answer with the commits at or after that point. A build with no
+     * repository has no such commit baked into it, and asking the service to
+     * resolve the position itself is strictly better than inventing one: it
+     * holds the chain, and for a project it is the only publisher of, the
+     * position IS the head.
+     */
+    if (this.git) {
+      params.push(["branch", this.git.branch]);
+      params.push(["commit", this.git.commit]);
+    }
     if (filters.patchIds) {
       for (const patchId of filters.patchIds) {
         params.push(["patch_id", patchId]);
@@ -7654,6 +8278,17 @@ class ValOpsHttp extends ValOps {
         if (parsed.success) {
           const errors = [];
           const data = parsed.data;
+          /*
+           * What the project expects of its publisher, remembered.
+           *
+           * Recorded here rather than returned because every caller of this
+           * already has what it needs and only the publish path asks the
+           * question -- and that path calls this first. See
+           * {@link publishRefusal}.
+           */
+          if (data.project) {
+            this.projectExpectation = data.project;
+          }
           for (const patchesRes of data.patches) {
             var _patchesRes$applied;
             patches.push({
@@ -7874,7 +8509,7 @@ class ValOpsHttp extends ValOps {
        * `saveSourceFilePatch`): groups are per branch, so a request without one
        * is not merely under-specified, it is rejected.
        */
-      const params = new URLSearchParams([["branch", this.branch]]);
+      const params = new URLSearchParams(this.git ? [["branch", this.git.branch]] : []);
       const res = await fetch(`${this.contentUrl}/v1/${this.project}/patch-groups?${params}`, {
         headers: this.authHeaders
       });
@@ -8026,8 +8661,10 @@ class ValOpsHttp extends ValOps {
         patchId,
         parentPatchId: parentRef.type === "patch" ? parentRef.patchId : null,
         baseSha,
-        commit: this.commitSha,
-        branch: this.branch,
+        ...(this.git ? {
+          commit: this.git.commit,
+          branch: this.git.branch
+        } : {}),
         coreVersion: Internal.VERSION.core,
         /*
          * Group membership in the SAME request as the patch.
@@ -8193,11 +8830,28 @@ class ValOpsHttp extends ValOps {
     });
   }
   async getSourceFile(path) {
+    /*
+     * There is no file to read without a repository to read it from.
+     *
+     * Reachable only through the CLI's debug snapshot now: the publish path
+     * does not call this for such a project at all -- see
+     * {@link ValOps.mirrorsSourceFiles} -- because there is nothing for it to
+     * produce. It is an error rather than an empty string because an empty
+     * `.val.ts` would be patched successfully and committed as a module that
+     * had lost all its content.
+     */
+    if (!this.git) {
+      return {
+        error: {
+          message: `Cannot read the source of ${path}: this project has no ` + "repository, so there is no `.val.ts` to read. Its content lives " + "in Val's content service, which is the store of record for it."
+        }
+      };
+    }
     const filesRes = await this.getHttpFiles([{
       filePath: path,
       location: "repo",
       root: this.root,
-      commitSha: this.commitSha
+      commitSha: this.git.commit
     }]);
     if (filesRes.error) {
       return filesRes;
@@ -8217,11 +8871,22 @@ class ValOpsHttp extends ValOps {
   async getBinaryFile(filePath) {
     // We could also just get this from public/ on the running server. Current approach feels more clean, but will be slower / puts more server load... We might want to change this
     const requestFiles = [];
+    if (!this.git) {
+      /*
+       * A published binary lives in the repository, and there is none.
+       *
+       * `null` is this method's existing "not found", which is what a caller
+       * already handles: the Studio falls back to the patch's own copy, which
+       * is where a managed project's files stay. See the note on local files
+       * in the content service's commit handler.
+       */
+      return null;
+    }
     requestFiles.push({
       filePath: filePath,
       location: "repo",
       root: this.root,
-      commitSha: this.commitSha
+      commitSha: this.git.commit
     });
     const filesRes = await this.getHttpFiles(requestFiles);
     if (filesRes.error) {
@@ -8400,7 +9065,6 @@ class ValOpsHttp extends ValOps {
   patchGroupId) {
     try {
       var _res$headers$get3;
-      const existingBranch = this.branch;
       const res = await fetch(`${this.contentUrl}/v1/${this.project}/commit`, {
         method: "POST",
         headers: {
@@ -8444,13 +9108,29 @@ class ValOpsHttp extends ValOps {
            * moved on.
            */
           modules: prepared.moduleVersions,
-          commit: this.commitSha,
+          /*
+           * WHERE THIS BUILD THOUGHT IT WAS -- and only for a project with a
+           * repository, which is the only thing that still reads it.
+           *
+           * The content service mints its own commit shas, so this is no
+           * longer the parent, and it never was the concurrency check: that is
+           * `expectedHeadCommitSha` against `newestCommitSha(patches.commits)`,
+           * which `/save` runs before it gets here. What is left is the git
+           * fast-forward check, which needs to know the commit this build read
+           * the branch at to tell whether the branch has moved under it.
+           *
+           * The branch goes with it. The project's branch is a column on the
+           * project, so a build asserting one could only ever disagree with
+           * the project it is publishing to.
+           */
+          ...(this.git ? {
+            commit: this.git.commit
+          } : {}),
           root: this.root,
           filesDirectory,
           baseSha: await this.getBaseSha(),
           committer,
           message,
-          existingBranch,
           newBranch,
           ...(patchGroupId !== undefined ? {
             patchGroupId
@@ -8463,7 +9143,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 {
@@ -10187,7 +10879,7 @@ async function initHandlerOptions(route, opts, config) {
     valContentUrl
   });
   if (isProxyMode) {
-    var _opts$versions, _opts$versions2;
+    var _opts$git, _opts$git2, _opts$versions, _opts$versions2;
     /*
      * Why this app is in http mode, in the message that says what is missing.
      *
@@ -10200,13 +10892,30 @@ async function initHandlerOptions(route, opts, config) {
     if (!maybeApiKey || !maybeValSecret) {
       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" + 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" + because);
+    /*
+     * A COMMIT IS NOT WHAT PUTS AN APP IN HTTP MODE. Credentials are.
+     *
+     * Both of these used to be required here, and the requirement was a
+     * repository disguised as a configuration check: a deployment with no
+     * commit to name -- one whose content service owns its content, which is
+     * now the normal case -- threw at boot, or, worse, never reached this
+     * branch at all and fell through to `fs` mode, looking for a working tree
+     * that was not there.
+     *
+     * Absent is a project with no repository to mirror commits into. The
+     * content service mints its own commit shas and is the store of record for
+     * content, so there is nothing missing: see `git` on {@link ValApiOptions}
+     * for what a commit is still FOR where there is one.
+     *
+     * Taken together or not at all. A commit without a branch names a point
+     * with no line of work to publish to, and a branch without a commit names
+     * a line with no position in it; either alone would be a half-configured
+     * repository that fails later, at a publish, rather than here.
+     */
+    const maybeGitCommit = ((_opts$git = opts.git) === null || _opts$git === void 0 ? void 0 : _opts$git.commit) || process.env.VAL_GIT_COMMIT;
+    const maybeGitBranch = ((_opts$git2 = opts.git) === null || _opts$git2 === void 0 ? void 0 : _opts$git2.branch) || process.env.VAL_GIT_BRANCH;
+    if (!!maybeGitCommit !== !!maybeGitBranch) {
+      throw new Error(`Val is configured with a git ${maybeGitCommit ? "commit" : "branch"} ` + `but no ${maybeGitCommit ? "branch" : "commit"}. Set both (the ` + "`git` option, or VAL_GIT_COMMIT and VAL_GIT_BRANCH) for a project " + "whose content is mirrored into a repository, or neither for one " + "whose content service is the store of record." + 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." + because);
@@ -10224,8 +10933,19 @@ async function initHandlerOptions(route, opts, config) {
       route,
       apiKey: maybeApiKey,
       valSecret: maybeValSecret,
-      commit: maybeGitCommit,
-      branch: maybeGitBranch,
+      /*
+       * Spread, so a project with no repository has no `git` key at all rather
+       * than one holding undefined. `ValOpsHttp` asks `git === null` to decide
+       * whether to send a branch and a commit with every request, and a key
+       * that is present-but-undefined is one more thing for that check to get
+       * wrong.
+       */
+      ...(maybeGitCommit && maybeGitBranch ? {
+        git: {
+          commit: maybeGitCommit,
+          branch: maybeGitBranch
+        }
+      } : {}),
       root: opts.root,
       project: maybeValProject,
       valEnableRedirectUrl,
@@ -10288,7 +11008,7 @@ function createValOps(valModules, options) {
     });
   }
   if (options.mode === "http") {
-    return new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, {
+    return new ValOpsHttp(options.valContentUrl, options.project, options.git ?? null, {
       apiKey: options.apiKey
     }, valModules, {
       formatter: options.formatter,
@@ -10494,6 +11214,7 @@ async function resolveRemoteFileAuth(options) {
 /** What a publish reports back, in either shape. */
 
 const ValServer = (valModules, options, callbacks) => {
+  var _options$git;
   const AIContentBlock = z.union([z.object({
     type: z.literal("text"),
     text: z.string()
@@ -10525,7 +11246,7 @@ const ValServer = (valModules, options, callbacks) => {
     url.searchParams.set("state", token);
     return url.toString();
   };
-  const commit = options.mode === "http" ? options.commit : undefined;
+  const commit = options.mode === "http" ? (_options$git = options.git) === null || _options$git === void 0 ? void 0 : _options$git.commit : undefined;
   const getAppErrorUrl = error => {
     if (!options.project) {
       throw new Error("Project is not set");
@@ -11122,12 +11843,24 @@ const ValServer = (valModules, options, callbacks) => {
          * start against a server that was working.
          */
         const mode = serverOps.patchesAreLocal ? "fs" : "http";
+        /*
+         * Why publishing is unavailable, so the Studio can say so.
+         *
+         * Spread rather than set to null, so a server that can publish sends
+         * no such key at all: the Studio's "can I publish" is then the
+         * presence of the field, and there is no null to mistake for a reason
+         * it failed to compute.
+         */
+        const publishRefusal = serverOps.publishRefusal();
         return {
           status: 200,
           json: {
             ...currentStat,
             profileId: profileId ?? null,
             mode,
+            ...(publishRefusal ? {
+              publishRefusal
+            } : {}),
             config: options.config
           }
         };
@@ -12316,6 +13049,29 @@ const ValServer = (valModules, options, callbacks) => {
           patchIds,
           excludePatchOps: false
         });
+        /*
+         * Can this deployment publish this project AT ALL?
+         *
+         * After the fetch above, deliberately: that call is what tells the
+         * data layer what the project expects, and asking before it would be
+         * asking a question nothing has answered yet. It is still before
+         * anything is written, which is the part that matters.
+         *
+         * The Studio already knows -- `/stat` carries the same refusal, so the
+         * action is disabled with the reason shown. This is the second half of
+         * that: a stat can be stale by a poll, and nothing may reach `prepare`
+         * on a project it cannot mirror.
+         */
+        const refusal = serverOps.publishRefusal();
+        if (refusal) {
+          return {
+            status: 409,
+            json: {
+              message: refusal.message,
+              publishRefusal: refusal
+            }
+          };
+        }
         /*
          * Exactly the patches this request consumes, and the ONLY ones it may
          * delete afterwards.