@valbuild/server 0.129.0 → 0.131.0

package/dist/valbuild-server.esm.js

@@ -5,7 +5,7 @@ import { derefPatch, Internal, extractValModules, computeValModuleShas, VAL_EXTE
 export { hasRemoteFileSchema } from '@valbuild/core';
 import * as path from 'path';
 import path__default from 'path';
-import fs, { promises } from 'fs';
+import fs from 'fs';
 import vm from 'node:vm';
 import { Module } from 'node:module';
 import { isSchemaSourceFixError, resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, JSONValue, PatchGroup, newestCommitSha, SerializedSchema, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api } from '@valbuild/shared/internal';
@@ -2495,6 +2495,17 @@ class ValOps {
       adopt[moduleFilePath] = source;
     }
     this.promoteCommittedSources(adopt);
+    /**
+     * And the `.val.ts` TEXT, for a store that has nowhere else to keep it.
+     *
+     * Everything above adopts the SOURCE — the data a module evaluates to. The
+     * file the patch was applied TO is a separate thing, and `getSourceFile` is
+     * what the next `prepare()` reads. In `fs` mode that is the disk, which
+     * `saveOrUploadFiles` has just rewritten, so this is a no-op. A store with
+     * no disk has to be told, or every later save re-reads the source as it was
+     * when the process started and silently reverts this one.
+     */
+    this.adoptPatchedSourceFiles(preparedCommit.patchedSourceFiles);
     /**
      * And the `.jsonValues()` entry content, which the sources above do not
      * carry — they hold markers. See {@link adoptedJsonEntries}.
@@ -4053,7 +4064,56 @@ class ValOps {
     });
   }
 
+  /**
+   * Take the `.val.ts` text a commit produced as the new committed source.
+   *
+   * A no-op where {@link getSourceFile} reads something the commit already
+   * wrote — the disk in `fs` mode, the content service in `http` mode. Override
+   * it in a store that holds the source itself. `null` means the commit deleted
+   * the file.
+   */
+  adoptPatchedSourceFiles(_files) {}
+
   // #region abstract ops
+  /**
+   * Whether the patches live HERE, in this server, or in Val's content service.
+   *
+   * Almost everything the routes branch on comes from this one fact, which is
+   * why it is a named property rather than an `instanceof`. If this server owns
+   * the store then there is no content service to authenticate to (so an absent
+   * or unverifiable session is anonymous rather than a 401), no shared store for
+   * a patch group to separate authors in, no deployments to report, and a
+   * "publish" writes what the host does with it rather than pushing a commit. If
+   * it does not, every one of those is the content service's and this server is
+   * relaying.
+   *
+   * There were two implementations when the routes were written and `instanceof
+   * ValOpsFS` meant this; a third made that reading wrong in a way that compiles
+   * silently -- a store that is local, answers none of the checks, and gets the
+   * http path with no content service behind it.
+   *
+   * It is also what `/stat` reports as `mode`. The wire name predates the third
+   * implementation and names a class, but the question the client is asking is
+   * this one: does it auto-save and hide the account panel, or does it publish.
+   */
+
+  /**
+   * Whether a request must carry a session this server verified.
+   *
+   * Split out of {@link patchesAreLocal}, which was answering two questions at
+   * once. "Does this store auto-save or publish" is a BEHAVIOUR question, and
+   * it is what `/stat` reports and the UI keys off. "May an unauthenticated
+   * request write here" is a SECURITY question. With two implementations the
+   * answers coincided -- fs is local dev where no credential exists, http is
+   * remote -- so one flag served both and nothing noticed.
+   *
+   * A third implementation splits them. `ValOpsMemory`'s store is local, which
+   * makes the first answer yes, and it is designed to run DEPLOYED, which makes
+   * the second answer no. Reusing one flag gave a deployed host `getAuth`
+   * returning anonymous success for a missing cookie, an invalid JWT, an
+   * unparseable payload, or no configured secret -- on all 29 routes, including
+   * the ones that create patches and publish.
+   */
 
   /**
    * Save a patch's binary file from a `data:...;base64,...` URL.
@@ -5650,6 +5710,13 @@ function serializeSchemaSafely(schema) {
 class ValOpsFS extends ValOps {
   static VAL_DIR = ".val";
   host;
+  /** The developer's own working tree. See {@link ValOps.patchesAreLocal}. */
+  patchesAreLocal = true;
+  /**
+   * The developer's own machine, where there is no credential to require and
+   * nothing to protect it from. See {@link ValOps.requiresAuth}.
+   */
+  requiresAuth = false;
   constructor(contentUrl, rootDir, valModules, options) {
     super(valModules, options);
     this.contentUrl = contentUrl;
@@ -7194,6 +7261,10 @@ const PATCH_GROUPS_CACHE_MS = 1000;
 class ValOpsHttp extends ValOps {
   authHeaders;
   root;
+  /** Val's content service owns the store. See {@link ValOps.patchesAreLocal}. */
+  patchesAreLocal = false;
+  /** See {@link ValOps.requiresAuth}. */
+  requiresAuth = true;
   constructor(contentUrl, project, commitSha,
   // TODO: CommitSha
   branch,
@@ -8625,6 +8696,643 @@ class ValOpsHttp extends ValOps {
   // #endregion history
 }
 
+/**
+ * One stored patch. Everything the ordered chain needs and nothing else.
+ */
+
+/**
+ * One pending binary file: an upload that has not been published yet.
+ *
+ * Keyed by the patch that carries it, exactly as `fs` mode keys the directory
+ * it writes to. The patch's own `file` op holds a hash, not the bytes, so these
+ * arrive on their own request and are joined up by `(patchId, filePath)`.
+ */
+
+/**
+ * Where pending patches live.
+ *
+ * The point of the interface: `ValOpsMemory` is not tied to memory. The default
+ * implementation below is explicitly NOT durable -- it dies with the process,
+ * or in a Worker with the isolate -- and a durable one (a Durable Object, whose
+ * single-threaded execution is the lock Val's fs store builds out of a file)
+ * is a swap rather than a rewrite.
+ *
+ * ORDER IS THE CONTRACT. `list()` returns patch ids in the order they were
+ * written, and that order is the chain: entry i's parent is entry i-1. This is
+ * the same decision `ValOpsFS` makes with `patches.log` -- the server decides
+ * where a patch goes, and it goes last -- and it exists for the same reason: an
+ * order held in the patches themselves lets a client working from a stale view
+ * strand every patch behind a parent that never landed.
+ */
+
+/** The default store. Not durable, deliberately and visibly. */
+class InMemoryPatchStore {
+  order = [];
+  byId = new Map();
+  async list() {
+    return [...this.order];
+  }
+  async get(patchId) {
+    return this.byId.get(patchId) ?? null;
+  }
+  async append(patch) {
+    if (!this.byId.has(patch.patchId)) {
+      this.order.push(patch.patchId);
+    }
+    this.byId.set(patch.patchId, patch);
+  }
+  async delete(patchIds) {
+    for (const patchId of patchIds) {
+      const at = this.order.indexOf(patchId);
+      if (at !== -1) {
+        this.order.splice(at, 1);
+      }
+      this.byId.delete(patchId);
+      // The bytes go with the patch. They are only reachable through it, so
+      // keeping them would be a leak with no reader -- and these are images.
+      for (const key of this.files.keys()) {
+        if (key.startsWith(`${patchId}\u0000`)) {
+          this.files.delete(key);
+        }
+      }
+    }
+  }
+
+  /*
+   * `\u0000` cannot occur in a patch id or a path, so the two halves of the key
+   * can never run together into a different pair.
+   *
+   * The PATH is normalised for the same reason `sourceFiles` is, and it is not
+   * cosmetic: an upload arrives as `/public/val/x.png`, and the publish step
+   * looks the same file up as `public/val/x.png` because that is what
+   * `splitRemoteRef` yields from a remote ref. `ValOpsFS` never noticed --
+   * `path.join` collapses the difference -- so this is another thing a
+   * filesystem was doing for free. Without it a remote image uploads fine,
+   * patches fine, and fails at publish with "No bytes held", naming a ref whose
+   * bytes are sitting right there under the other spelling.
+   */
+  static fileKey(patchId, filePath) {
+    return `${patchId}\u0000${filePath.replace(/^\//, "")}`;
+  }
+  files = new Map();
+  async putFile(file) {
+    this.files.set(InMemoryPatchStore.fileKey(file.patchId, file.filePath), file);
+  }
+  async getFile(patchId, filePath) {
+    return this.files.get(InMemoryPatchStore.fileKey(patchId, filePath)) ?? null;
+  }
+  async deleteFile(patchId, filePath) {
+    this.files.delete(InMemoryPatchStore.fileKey(patchId, filePath));
+  }
+  async filesOf(patchId) {
+    return [...this.files.values()].filter(file => file.patchId === patchId);
+  }
+}
+/**
+ * A `ValOps` for a host that is neither a developer's machine nor
+ * content.val.build.
+ *
+ * EXPERIMENTAL -- see VAL_PROMPT.md.
+ *
+ * `fs` mode assumes a working tree it can watch and write; `http` mode assumes
+ * the content API owns the patch chain and a commit means a git commit. A host
+ * that builds and publishes its own output is neither: it holds the source
+ * already, it has nowhere to watch, and its "commit" is a new build.
+ *
+ * What this deliberately does NOT do:
+ *
+ * - **No filesystem.** Source comes from `sourceFiles`, patches from a store.
+ * - **No watching.** `getStat` still long-polls -- the hold is what paces the
+ *   client -- but it parks on a signal rather than racing a timer against an
+ *   mtime poll that can never observe anything here. Nothing can edit files
+ *   behind Val's back: source changes only when the host publishes, and that
+ *   replaces the process.
+ * - **Pending binary files, but no PUBLISHED local ones.** An upload is held in
+ *   the patch store like any other pending change, so the Studio can preview it
+ *   before it is published. What this has no answer for is a file that is
+ *   already published and served from a `/public` directory: this configuration
+ *   uses Val's REMOTE files, where a published image lives on the content host
+ *   and the source carries a URL. `getBinaryFile` answers `null` for those --
+ *   a miss, not a fault -- and `getBinaryFileMetadata` refuses by name.
+ * - **No git history.** There is no repository here, so the history methods
+ *   answer `not-supported-in-fs-mode` -- the same closed error `ValOpsFS`
+ *   uses, so the History UI degrades the way it already knows how rather than
+ *   inventing a commit list. See the note above `listCommits`.
+ */
+class ValOpsMemory extends ValOps {
+  /**
+   * The host's own store -- see {@link ValOps.patchesAreLocal}. `true` for the
+   * same reason `fs` mode is: nothing is relayed to a content service, so
+   * there is no session to verify against one and no group to separate authors
+   * in. Where the two differ is not something a route asks about.
+   */
+  patchesAreLocal = true;
+  /**
+   * Required, unless the host explicitly takes the boundary itself.
+   *
+   * `patchesAreLocal` is true here and that is about publishing, not about who
+   * may write -- see {@link ValOps.requiresAuth}.
+   */
+  requiresAuth;
+  store;
+  /**
+   * The project's source, keyed WITHOUT a leading slash.
+   *
+   * Two spellings reach this. A host keys by project-relative path
+   * (`src/routes/page.val.ts`) because that is what it built from; Val asks and
+   * commits with a leading slash (`/src/routes/page.val.ts`). Normalised on the
+   * way in so there is one entry per file — holding both spellings would let a
+   * commit update one and leave the other as the stale answer.
+   *
+   * Not `readonly`: a save replaces the files it rewrote. See
+   * {@link adoptPatchedSourceFiles}.
+   */
+  sourceFiles;
+  contentUrl;
+  constructor(valModules, options) {
+    super(valModules, options);
+    this.store = options.patchStore ?? new InMemoryPatchStore();
+    this.contentUrl = options.contentUrl;
+    this.requiresAuth = !options.unsafelyAllowUnauthenticated;
+    if (options.unsafelyAllowUnauthenticated) {
+      console.warn("Val: serving memory mode WITHOUT authentication. Every request that " + "reaches this server may read content, create patches and trigger a " + "publish. Only correct if the host authorises requests before they " + "get here.");
+    }
+    this.sourceFiles = Object.fromEntries(Object.entries(options.sourceFiles).map(([path, text]) => [ValOpsMemory.key(path), text]));
+  }
+
+  // #region the six that carry the mode
+
+  async onInit() {
+    // Nothing to prepare: there is no directory to create and no store to open.
+  }
+
+  /**
+   * Requests parked in {@link getStat}, waiting for something to happen.
+   *
+   * See there for why this exists. Resolved and emptied by
+   * {@link announceChange}; never rejected, because a waiter that gives up does
+   * so on its own timeout.
+   */
+  statWaiters = [];
+
+  /**
+   * Writes so far. Sampled before reading, compared after registering.
+   *
+   * The registration is not atomic with the read above it: a patch written
+   * between `currentStat()` and `statWaiters.push` was announced to a list this
+   * waiter was not yet on, so the request slept the full interval with a change
+   * already sitting there. Comparing the count closes that window without a
+   * lock.
+   */
+  changeCount = 0;
+
+  /** Wake every parked `getStat`. Called by this instance's own writes. */
+  announceChange() {
+    this.changeCount += 1;
+    const waiting = this.statWaiters;
+    this.statWaiters = [];
+    for (const wake of waiting) {
+      wake();
+    }
+  }
+  async currentStat() {
+    return {
+      baseSha: await this.getBaseSha(),
+      schemaSha: await this.getSchemaSha(),
+      sourcesSha: await this.getSourcesSha(),
+      patches: await this.store.list()
+    };
+  }
+  async getStat(params) {
+    /*
+     * A long poll, and it has to be one -- but parked on a SIGNAL rather than a
+     * timer.
+     *
+     * The hold is what paces the client. `useStatus.ts` sets `wait: 0` between
+     * stats unless it has a WebSocket, with the comment "we are long polling so
+     * no point in waiting": the server holding the request open IS the rate
+     * limit. An earlier version of this method answered immediately, on the
+     * reasoning that nothing can edit files behind Val's back in an isolate --
+     * true, and beside the point. It turned a 20s poll into a request every
+     * 6ms, which is worse than what it replaced.
+     *
+     * What was actually wrong with `fs` mode here is not the hold, it is the
+     * WATCHING: it races a 250ms mtime poll and an `fs.watch`, neither of which
+     * can observe anything in an isolate (the shim's `watch` never fires and
+     * mtime is always 0), so it burns CPU for 20s to learn nothing. This owns
+     * its store, so it is TOLD instead -- zero timers while parked, and a patch
+     * written by another tab is seen at once rather than up to 250ms later.
+     *
+     * The timeout is the backstop, and it is not only for an idle branch: a
+     * store shared between isolates (a Durable Object -- see ValPatchStore) can
+     * change without this instance writing anything, and nothing would announce
+     * that. So it re-reads on the way out rather than assuming `no-change`.
+     */
+    // Before the read, not after: anything that happens from here on must be
+    // observed, either by `differs` below or by the recheck in parkUntilChange.
+    const seenAt = this.changeCount;
+    const before = await this.currentStat();
+    const differs = now => params === null || params.baseSha !== now.baseSha || params.schemaSha !== now.schemaSha || (params.patches ?? []).join(",") !== now.patches.join(",");
+
+    // Already behind: answer now. This is the case that matters for latency --
+    // the client has just written a patch and is asking what happened.
+    if (differs(before)) {
+      return {
+        type: "did-change",
+        ...before
+      };
+    }
+    await this.parkUntilChange(seenAt);
+    const after = await this.currentStat();
+    return {
+      type: differs(after) ? "did-change" : "no-change",
+      ...after
+    };
+  }
+
+  /** Resolves on the next write here, or when the poll interval runs out. */
+  parkUntilChange(seenAt) {
+    var _this$options;
+    const timeoutMs = ((_this$options = this.options) === null || _this$options === void 0 ? void 0 : _this$options.statPollingInterval) ?? 20_000;
+    return new Promise(resolve => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        // Cleared on BOTH paths: a change that wins the race leaves a 20s timer
+        // behind otherwise, and in a Worker a pending timer is a reason to keep
+        // the isolate alive.
+        clearTimeout(timer);
+        // Removed on BOTH paths too, for the same kind of reason. Only
+        // `announceChange` emptied this list, so a timed-out waiter stayed on
+        // it forever: one dead closure per idle poll, on a server that polls
+        // every 20 seconds indefinitely, and a later write walked all of them.
+        const at = this.statWaiters.indexOf(done);
+        if (at !== -1) {
+          this.statWaiters.splice(at, 1);
+        }
+        resolve();
+      };
+      const timer = setTimeout(done, timeoutMs);
+      this.statWaiters.push(done);
+      // Registered; now look again. A write in the gap announced to a list this
+      // waiter was not on yet, and waiting 20s for news that already arrived is
+      // the bug this closes.
+      if (this.changeCount !== seenAt) {
+        done();
+      }
+    });
+  }
+  async fetchPatches(filters) {
+    // An empty `patchIds` means "no filter", not "none": both shipped
+    // implementations read it that way and callers rely on it. See
+    // `scopedModulePatches` in ValOps.ts, which says why at length.
+    const requested = filters.patchIds && filters.patchIds.length > 0 ? new Set(filters.patchIds) : null;
+    const order = await this.store.list();
+    const patches = [];
+    for (const patchId of order) {
+      if (requested !== null && !requested.has(patchId)) {
+        continue;
+      }
+      const stored = await this.store.get(patchId);
+      if (!stored) {
+        continue;
+      }
+      patches.push({
+        patchId: stored.patchId,
+        path: stored.path,
+        patch: stored.patch,
+        createdAt: stored.createdAt,
+        authorId: stored.authorId,
+        baseSha: stored.baseSha,
+        // Nothing here is ever applied-at-a-commit: a publish in this mode
+        // rebuilds the site and starts a new process, so a patch that has been
+        // applied is a patch this store no longer holds.
+        appliedAt: null
+      });
+    }
+    // The cast is unavoidable: the return type is conditional on a generic
+    // TypeScript cannot narrow from a value. `ValOpsFS` does the same.
+    return {
+      patches: filters.excludePatchOps ? patches.map(({
+        patch: _patch,
+        ...rest
+      }) => ({
+        ...rest,
+        patch: undefined
+      })) : patches
+    };
+  }
+  async saveSourceFilePatch(path, patch, patchId,
+  /*
+   * Ignored, exactly as in `fs` mode, and named so that is visible.
+   *
+   * The store's order IS the chain, so the server decides where a patch goes
+   * and it goes last. There is no parent to name, and so nothing that can
+   * point at nothing. A patch computed against a different state is caught
+   * where it shows -- applying it -- rather than by refusing the write.
+   */
+  _parentRef, authorId, _sessionId,
+  /* No shared store and no second author yet, so nothing for a group to
+   * separate. Named rather than omitted: TypeScript allows an implementation
+   * to take fewer parameters, so dropping it would look identical to
+   * handling it. */
+  _patchGroup) {
+    await this.store.append({
+      patchId,
+      path,
+      patch,
+      authorId,
+      createdAt: new Date().toISOString(),
+      baseSha: await this.getBaseSha()
+    });
+    // Any `getStat` parked on this instance answers now instead of waiting out
+    // its timeout. This is the whole reason the hold can be free: the store is
+    // ours, so there is nothing to poll for.
+    this.announceChange();
+    return result.ok({
+      patchId
+    });
+  }
+
+  /** One spelling for a path, whichever the caller used. See sourceFiles. */
+  static key(path) {
+    return path.replace(/^\//, "");
+  }
+
+  /**
+   * A save has rewritten these files; they are the committed source now.
+   *
+   * Without this every save after the first re-reads the source as it was when
+   * this object was built, applies only its own patches to that, and parks a
+   * file that reverts everything saved before it -- with no error, because
+   * applying the patch to the ORIGINAL text succeeds. The Studio auto-saves, so
+   * that is not an edge case: it is most of a session's work.
+   *
+   * `fs` mode gets this for free -- `saveOrUploadFiles` writes the disk that
+   * `getSourceFile` reads. There is no disk here, so it is written down.
+   */
+  adoptPatchedSourceFiles(files) {
+    for (const [path, text] of Object.entries(files)) {
+      const key = ValOpsMemory.key(path);
+      if (text === null) {
+        delete this.sourceFiles[key];
+      } else {
+        this.sourceFiles[key] = text;
+      }
+    }
+  }
+  async getSourceFile(path) {
+    const data = this.sourceFiles[ValOpsMemory.key(path)];
+    if (data === undefined) {
+      return {
+        error: {
+          message: `File not found: ${path}. In this mode the host hands Val its ` + `source, so a missing file means the host did not ship it -- not ` + `that it is absent from a disk.`
+        }
+      };
+    }
+    return {
+      data
+    };
+  }
+  async deletePatches(patchIds) {
+    await this.store.delete(patchIds);
+    this.announceChange();
+    return {
+      deleted: patchIds
+    };
+  }
+
+  /**
+   * Push this commit's pending binary files to Val's content host.
+   *
+   * The half of publishing that `commitPrepared` cannot do. Val's remote files
+   * upload at PUBLISH, not when the image is added: until then the bytes are a
+   * pending change like any other, held by {@link ValPatchStore}. So a publish
+   * has to walk the descriptors and push each one before the source that
+   * references it goes live -- otherwise the new build ships a URL that 404s.
+   *
+   * `ValOpsFS.saveOrUploadFiles` does the same loop, alongside two things this
+   * has no use for: copying LOCAL binaries into a working tree, and writing the
+   * source files (which is `commitPrepared` here). Kept separate rather than
+   * shared, because the shapes only look alike.
+   *
+   * Errors are collected rather than thrown. One image that will not upload
+   * should name itself and leave the rest of the publish decidable, rather than
+   * failing a save that has already applied its patches.
+   */
+  async uploadRemoteFiles(preparedCommit, auth) {
+    var _this$options2;
+    const uploaded = [];
+    const errors = {};
+    const project = (_this$options2 = this.options) === null || _this$options2 === void 0 ? void 0 : _this$options2.config.project;
+    const descriptors = Object.entries(preparedCommit.patchedBinaryFilesDescriptors);
+    const remote = descriptors.filter(([, descriptor]) => descriptor.remote);
+
+    /*
+     * A LOCAL descriptor is refused, not ignored.
+     *
+     * This mode has no published local-file path -- there is no `/public` to
+     * write into -- and the class docstring says so. But filtering to `remote`
+     * meant a local one fell through silently, and the caller carries on:
+     * source is adopted and the patch deleted, so `/save` answers 200 and the
+     * uploaded bytes are gone with nothing anywhere saying why.
+     *
+     * Erroring here keeps the patch, because a save that cannot store what it
+     * was given has not succeeded.
+     */
+    for (const [ref, descriptor] of descriptors) {
+      if (descriptor.remote) continue;
+      errors[ref] = {
+        message: "Cannot publish a local file in this mode: there is no directory to " + "publish it to. Configure the project for Val's remote files, which " + "is what this configuration uploads."
+      };
+    }
+    if (remote.length === 0) {
+      return {
+        uploaded,
+        errors
+      };
+    }
+    if (!this.contentUrl || !project) {
+      // Named separately from a failed upload: nothing was attempted, and the
+      // fix is configuration rather than a retry.
+      for (const [ref] of remote) {
+        errors[ref] = {
+          message: "Cannot publish a remote file: this server has no " + (!project ? "`project` in val.config" : "content host configured") + ". Remote files need both, plus an api key."
+        };
+      }
+      return {
+        uploaded,
+        errors
+      };
+    }
+    for (const [ref, {
+      patchId
+    }] of remote) {
+      const split = Internal.remote.splitRemoteRef(ref);
+      if (split.status === "error") {
+        errors[ref] = {
+          message: "Failed to split remote ref: " + ref
+        };
+        continue;
+      }
+      const bytes = await this.getBase64EncodedBinaryFileFromPatch(split.filePath, patchId);
+      if (!bytes) {
+        errors[ref] = {
+          message: `No bytes held for ${ref} (patch ${patchId}). The upload either never arrived or was dropped with its patch.`
+        };
+        continue;
+      }
+      const res = await uploadRemoteFile(this.contentUrl, project, split.bucket, split.fileHash, getFileExt(split.filePath), bytes, auth);
+      if (!res.success) {
+        errors[ref] = {
+          message: res.error
+        };
+        continue;
+      }
+      uploaded.push(ref);
+    }
+    return {
+      uploaded,
+      errors
+    };
+  }
+
+  // #endregion
+  // #region published local files -- these refuse rather than pretend
+
+  remoteOnly(method) {
+    throw new Error(`${method} reads a PUBLISHED file from a local directory, and this ` + `configuration uses Val's REMOTE files: a published file lives on the ` + `content host and the source carries its URL. Pending uploads are held ` + `here and do work -- see saveBase64EncodedBinaryFileFromPatch.`);
+  }
+  async saveBase64EncodedBinaryFileFromPatch(filePath,
+  /*
+   * Ignored, as in `fs` mode: the file is keyed by the patch that carries it,
+   * so there is no parent to resolve.
+   */
+  _parentRef, patchId, data, _type, metadata) {
+    if (data === null) {
+      // `null` records a DELETION. This is why the byte-taking sibling cannot
+      // replace this method: there would be nothing to hand it.
+      await this.store.deleteFile(patchId, filePath);
+      return {
+        patchId,
+        filePath
+      };
+    }
+    const buffer = bufferFromDataUrl(data);
+    if (!buffer) {
+      return {
+        error: {
+          message: "Could not create buffer from data url. Not a data url? First chars were: " + data.slice(0, 20)
+        }
+      };
+    }
+    await this.store.putFile({
+      patchId,
+      filePath,
+      data: buffer,
+      metadata
+    });
+    return {
+      patchId,
+      filePath
+    };
+  }
+  async getBase64EncodedBinaryFileFromPatch(filePath, patchId,
+  /*
+   * Not consulted, and `fs` mode does not consult it either: a remote ref has
+   * already been split by the caller, so what arrives here is the path inside
+   * it and the pair (patchId, filePath) is the whole key.
+   */
+  _remote) {
+    var _await$this$store$get;
+    return ((_await$this$store$get = await this.store.getFile(patchId, filePath)) === null || _await$this$store$get === void 0 ? void 0 : _await$this$store$get.data) ?? null;
+  }
+  async getBase64EncodedBinaryFileMetadataFromPatch(filePath, type, patchId, _remote) {
+    const file = await this.store.getFile(patchId, filePath);
+    if (!file || file.metadata === undefined) {
+      return {
+        errors: [{
+          message: "Metadata file not found",
+          filePath
+        }]
+      };
+    }
+    /*
+     * Checked, not trusted. The metadata is whatever the client sent with the
+     * upload, and a missing `width` on an image is the difference between a
+     * layout that reserves space and one that jumps -- reported here, where the
+     * field is named, rather than surfacing as an undefined further on.
+     */
+    const fieldErrors = getFieldsForType(type).filter(field => !(field in file.metadata)).map(field => ({
+      message: `Expected fields for type: ${type}. Field not found: '${field}'`,
+      field
+    }));
+    if (fieldErrors.length > 0) {
+      return {
+        errors: fieldErrors
+      };
+    }
+    return {
+      metadata: file.metadata
+    };
+  }
+  async getBinaryFile(_filePathOrRef) {
+    // Null rather than a throw: callers treat this as "no such file", and a
+    // read of a local file in a remote-files project is a miss, not a fault.
+    return null;
+  }
+  async getBinaryFileMetadata(_filePath, _type) {
+    return this.remoteOnly("getBinaryFileMetadata");
+  }
+
+  // #endregion
+  // #region no git here
+
+  // The same answer `ValOpsFS` gives, for the same reason and reusing its
+  // error: history is a thing the content service holds, and there is no
+  // repository behind this mode either. `not-supported-in-fs-mode` is the
+  // closed union's member for exactly that, and the Studio already knows how
+  // to show it -- a mode-specific member would be a new state to write UI for
+  // that says the same sentence.
+
+  async listCommits() {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getCommitPatches() {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getCommitModules() {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getCommitAffectedFiles() {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getFileAtCommit() {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  gitPathOfModule(
+  // Unused: there is no repository for a module path to be relative to.
+  _moduleFilePath) {
+    return result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  // #endregion history
+}
+
+/** Kept exported so a host can name the error shape it may get back. */
+
 /**
  * Everything that can go wrong reading, replaying or restoring history.
  *
@@ -9172,15 +9880,27 @@ moduleGitPath, valTsSource, key) {
   return result.ok(path__default.posix.join(moduleDir, entry.importPath));
 }
 
-const host = process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST;
+/**
+ * The fallback content host.
+ *
+ * Read at module scope, which is why {@link getSettings} takes an override: a
+ * host that bundles its dependencies SEPARATELY from its own code cannot set
+ * this. Such a build inlines env vars into the app and leaves dependency chunks
+ * alone, so `process.env.VAL_CONTENT_URL` here is whatever it was when the
+ * chunk was built -- usually nothing. A caller that knows the content url has
+ * to be able to say so.
+ */
+const defaultHost$1 = process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST;
 const SettingsSchema = z.object({
   publicProjectId: z.string(),
   remoteFileBuckets: z.array(z.object({
     bucket: z.string()
   }))
 });
-async function getSettings(projectName, auth) {
+async function getSettings(projectName, auth, /** Overrides {@link defaultHost}. See the note there for why this exists. */
+contentUrl) {
   try {
+    const host = contentUrl || defaultHost$1;
     const response = await fetch(`${host}/v1/${projectName}/settings`, {
       headers: "pat" in auth ? {
         "x-val-pat": auth.pat,
@@ -9307,6 +10027,73 @@ const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
  * var alone.
  */
 async function initHandlerOptions(route, opts, config) {
+  /*
+   * A host that handed us the source has settled the question.
+   *
+   * First, and without consulting the environment: the other two modes are
+   * inferred (an api key in the env is enough to make a project "proxy"), and
+   * this one cannot be, so an env var that happens to be set must not be able
+   * to take a host that supplied its own source and point it at a content
+   * service instead.
+   */
+  if (opts.sourceFiles !== undefined) {
+    const valContentUrl = opts.valContentUrl || process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST;
+    const valBuildUrl = opts.valBuildUrl || process.env.VAL_BUILD_URL || DEFAULT_VAL_BUILD_URL;
+    /*
+     * The same warning the other two modes get, and for the same reason.
+     *
+     * Returning early here skipped it, and the early return is about MODE
+     * INFERENCE -- not about which URLs are safe. This mode still sends
+     * `apiKey` to `valContentUrl` for remote-file settings and uploads, so a
+     * host configured with a non-loopback `http://` content URL was putting a
+     * credential on the wire with none of the warning fs and http modes give
+     * for exactly that.
+     */
+    warnIfInsecureUrls({
+      valBuildUrl,
+      valContentUrl
+    });
+    return {
+      mode: "memory",
+      route,
+      sourceFiles: opts.sourceFiles,
+      patchStore: opts.patchStore,
+      unsafelyAllowUnauthenticated: opts.unsafelyAllowUnauthenticated,
+      valContentUrl,
+      valBuildUrl,
+      valEnableRedirectUrl: opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL,
+      valDisableRedirectUrl: opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL,
+      apiKey: opts.apiKey || process.env.VAL_API_KEY,
+      valSecret: opts.valSecret || process.env.VAL_SECRET,
+      project: opts.project || process.env.VAL_PROJECT,
+      config
+    };
+  }
+  /*
+   * `VAL_MODE=memory` says the host MEANT to hold the source, and did not.
+   *
+   * It cannot 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.
+   *
+   * 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
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * 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).");
+  }
+  // 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.");
+  }
   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);
@@ -9420,6 +10207,29 @@ function createValOps(valModules, options) {
       config: options.config
     });
   }
+  if (options.mode === "memory") {
+    /*
+     * No backend to authenticate AGAINST, which is not the same as nothing to
+     * authenticate. That conflation is what made this mode serve every route to
+     * anyone who could reach the port: fs mode skips auth because it is a
+     * developer's own machine, and this one reuses its local-store flag while
+     * running deployed. It requires a verified session unless the host says it
+     * has its own boundary -- see `unsafelyAllowUnauthenticated`.
+     *
+     * The host still holds the source and decides what a publish means; that
+     * part is `commitPrepared` on ValServerOptions.
+     */
+    return new ValOpsMemory(valModules, {
+      formatter: options.formatter,
+      config: options.config,
+      sourceFiles: options.sourceFiles,
+      patchStore: options.patchStore,
+      unsafelyAllowUnauthenticated: options.unsafelyAllowUnauthenticated,
+      // For pushing remote files at publish. A project with no `s.image()`
+      // never reaches it, which is why nothing above requires it.
+      contentUrl: options.valContentUrl
+    });
+  }
   throw new Error(
   // The union is exhausted above; this catches a config that came from
   // somewhere untyped.
@@ -9538,12 +10348,23 @@ async function resolveRemoteFileAuth(options) {
     };
   }
   if (options.mode !== "fs") {
-    // Unreachable through `initHandlerOptions`, which refuses to build a proxy
-    // config without an api key. Kept because this is exported.
+    /*
+     * `api-key-missing`, and the distinction matters to whoever reads it.
+     *
+     * The PAT below is read from a file in the server's own working directory,
+     * which only `fs` mode has. Every other mode can be authenticated one way,
+     * with an api key -- so the Studio must not offer `val login` here. It did,
+     * because "local" used to mean "fs" and the third mode made that false: the
+     * dialog told people to run a command, in a directory, that could not have
+     * helped even if they found the right one.
+     *
+     * `project-not-configured` was also just wrong. The project may be
+     * perfectly well configured; it is the credential that is absent.
+     */
     return {
       status: "error",
-      errorCode: "project-not-configured",
-      message: "Remote file auth is not configured"
+      errorCode: "api-key-missing",
+      message: "Remote files need an api key here: this server cannot read a " + "personal access token, because that is a file in a working directory " + "and it has none. Set VAL_API_KEY."
     };
   }
   // `options.cwd`, which `initHandlerOptions` sets from `process.cwd()`. The
@@ -9578,6 +10399,11 @@ async function resolveRemoteFileAuth(options) {
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
+
+/** What {@link ValServerOptions.publishOverride} is given. */
+
+/** What a publish reports back, in either shape. */
+
 const ValServer = (valModules, options, callbacks) => {
   const AIContentBlock = z.union([z.object({
     type: z.literal("text"),
@@ -9672,8 +10498,17 @@ const ValServer = (valModules, options, callbacks) => {
   };
   const getAuth = cookies => {
     const cookie = cookies[VAL_SESSION_COOKIE];
+    /*
+     * `requiresAuth`, not `patchesAreLocal`.
+     *
+     * These four exits return anonymous SUCCESS -- `{ error: null }` -- and all
+     * 29 routes below treat that as authorised. That is right for fs mode,
+     * which is a developer's own machine with no credential to require. It was
+     * keyed on the wrong question: a local patch store is about publishing, not
+     * about who may write, and memory mode is local AND deployed.
+     */
     if (!options.valSecret) {
-      if (serverOps instanceof ValOpsFS) {
+      if (!serverOps.requiresAuth) {
         return {
           error: null,
           id: null
@@ -9687,7 +10522,7 @@ const ValServer = (valModules, options, callbacks) => {
     if (typeof cookie === "string") {
       const verifiedToken = verifyJwt(cookie, options.valSecret);
       if (!verifiedToken.success) {
-        if (serverOps instanceof ValOpsFS) {
+        if (!serverOps.requiresAuth) {
           return {
             error: null,
             id: null
@@ -9699,7 +10534,7 @@ const ValServer = (valModules, options, callbacks) => {
       }
       const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
       if (!verification.success) {
-        if (serverOps instanceof ValOpsFS) {
+        if (!serverOps.requiresAuth) {
           return {
             error: null,
             id: null
@@ -9713,7 +10548,7 @@ const ValServer = (valModules, options, callbacks) => {
         id: verification.data.sub
       };
     } else {
-      if (serverOps instanceof ValOpsFS) {
+      if (!serverOps.requiresAuth) {
         return {
           error: null,
           id: null
@@ -10115,7 +10950,10 @@ const ValServer = (valModules, options, callbacks) => {
           return remoteFileAuthRes;
         }
         const remoteFileAuth = remoteFileAuthRes.json.remoteFileAuth;
-        const settingsRes = await getSettings(options.project, remoteFileAuth);
+
+        // The content url this server was CONFIGURED with, not whatever was in
+        // the environment when @valbuild/server was built. See getSettings.
+        const settingsRes = await getSettings(options.project, remoteFileAuth, options.valContentUrl);
         if (!settingsRes.success) {
           console.warn("Could not get remote files settings: " + settingsRes.message);
           return {
@@ -10184,15 +11022,17 @@ const ValServer = (valModules, options, callbacks) => {
             json: currentStat.error
           };
         }
-        const mode = serverOps instanceof ValOpsFS ? "fs" : serverOps instanceof ValOpsHttp ? "http" : "unknown";
-        if (mode === "unknown") {
-          return {
-            status: 500,
-            json: {
-              message: "Server mode is neither fs nor http - this is an internal Val bug"
-            }
-          };
-        }
+        /*
+         * The wire value names a class and the question it answers does not.
+         *
+         * The client reads `mode` to decide whether it auto-saves and hides the
+         * account panel, or whether it publishes and shows deployments -- which
+         * is {@link ValOps.patchesAreLocal} and nothing else. It was derived by
+         * `instanceof` while there were exactly two implementations, so a third
+         * local store fell through to `"unknown"` and the Studio refused to
+         * start against a server that was working.
+         */
+        const mode = serverOps.patchesAreLocal ? "fs" : "http";
         return {
           status: 200,
           json: {
@@ -10263,7 +11103,7 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           // In FS mode patch-file uploads are buffered through this server (no remote round-trip),
           // so baseUrl points at /api/val/upload. AI image uploads, however, go straight to the
           // content host — we resolve a contentBaseUrl + a PAT-issued nonce here so the browser
@@ -10273,6 +11113,19 @@ const ValServer = (valModules, options, callbacks) => {
           let contentAuthNonce = null;
           if (!options.project) {
             console.warn("Direct content-host uploads (AI images) disabled: no `project` set in val.config (and VAL_PROJECT env var is not set).");
+          } else if (!(serverOps instanceof ValOpsFS)) {
+            /*
+             * Presigning needs a content host to presign AGAINST, and a local
+             * store does not necessarily have one configured: `fs` mode has the
+             * developer's `valContentUrl`, and a host holding its own source has
+             * no such setting.
+             *
+             * Warned and disabled, like the missing-project case above, rather
+             * than failing the request: everything else this route answers --
+             * the patch upload base url -- still works, and the only thing lost
+             * is the browser posting AI images straight to the content host.
+             */
+            console.warn("Direct content-host uploads (AI images) disabled: this store has no content host to presign against.");
           } else {
             const authDataRes = await getRemoteFileAuth();
             if (authDataRes.status !== 200) {
@@ -10354,7 +11207,7 @@ const ValServer = (valModules, options, callbacks) => {
           patchIds
         } = req.body;
         const withPatchIds = req.body.withPatchIds ?? [];
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return {
             status: 200,
             json: {
@@ -10417,7 +11270,7 @@ const ValServer = (valModules, options, callbacks) => {
           patchIds
         } = req.body;
         const withPatchIds = req.body.withPatchIds ?? [];
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return {
             status: 200,
             json: {
@@ -10496,7 +11349,7 @@ const ValServer = (valModules, options, callbacks) => {
           } : {}),
           withPatchIds: requestedWith ?? []
         } : undefined;
-        if (patchGroup !== undefined && serverOps instanceof ValOpsFS) {
+        if (patchGroup !== undefined && serverOps.patchesAreLocal) {
           /*
            * `fs` has no shared store and one author, so there is no group to
            * join. Refused rather than acknowledged: answering 200 would tell the
@@ -11267,7 +12120,7 @@ const ValServer = (valModules, options, callbacks) => {
         }
         const authDataRes = await getRemoteFileAuth();
         if (authDataRes.status !== 200) {
-          if (serverOps instanceof ValOpsFS && authDataRes.json.errorCode === "pat-error") {
+          if (serverOps.patchesAreLocal && authDataRes.json.errorCode === "pat-error") {
             return {
               status: 200,
               json: {
@@ -11324,7 +12177,7 @@ const ValServer = (valModules, options, callbacks) => {
             };
           }
         };
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return execFetch(getProfileAuthHeaders(authData, null, "application/json"));
         }
         if (!options.valSecret) {
@@ -11440,7 +12293,7 @@ const ValServer = (valModules, options, callbacks) => {
          * editing is told what was thrown away.
          */
         let removed = [];
-        if (preparedCommit.hasErrors && serverOps instanceof ValOpsFS) {
+        if (preparedCommit.hasErrors && serverOps.patchesAreLocal) {
           removed = computePatchesToDrop(preparedCommit);
           /*
            * Nothing to drop means nothing a second `prepare` could do better.
@@ -11492,35 +12345,93 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        if (serverOps instanceof ValOpsFS) {
-          var _remoteFileAuthRes;
-          const isRemoteRequired = getIsRemoteRequired(await serverOps.getSchemas());
-          let mode;
-          let remoteFileAuthRes;
-          if (isRemoteRequired) {
-            mode = "upload-remote";
-            remoteFileAuthRes = await getRemoteFileAuth();
-          } else {
-            mode = "skip-remote";
+        if (serverOps.patchesAreLocal) {
+          /*
+           * Writing the files is the one step that is not shared.
+           *
+           * Everything around it is: applying the patches, telling the ops the
+           * sources moved, handing the result to the host, dropping the patches
+           * this request consumed. Only the destination differs -- `fs` mode has
+           * a working tree to write into and remote binaries to push, and a host
+           * that holds its own source has neither. So this branch is on the
+           * store that CAN write files rather than on "is this local", which is
+           * what the rest of the flow asks.
+           */
+          /*
+           * Remote binary files, which publish separately from the source.
+           *
+           * Val uploads a remote file at PUBLISH rather than when it is added:
+           * until then the bytes are a pending change like any other. So a
+           * local store has to push them before the source that references them
+           * goes live, or the new build ships a URL that 404s. `ValOpsFS` does
+           * this inside `saveOrUploadFiles`, alongside writing its working
+           * tree; a store with no working tree does only the push.
+           */
+          if (serverOps instanceof ValOpsMemory) {
+            const isRemoteRequired = getIsRemoteRequired(await serverOps.getSchemas());
+            if (isRemoteRequired) {
+              const authRes = await getRemoteFileAuth();
+              if (authRes.status !== 200) {
+                return authRes;
+              }
+              const uploadRes = await serverOps.uploadRemoteFiles(preparedCommit, authRes.json.remoteFileAuth);
+              if (Object.keys(uploadRes.errors).length > 0) {
+                console.error("Val: Failed to upload remote files", uploadRes.errors);
+                return {
+                  status: 400,
+                  json: {
+                    message: "Failed to save files",
+                    details: Object.entries(uploadRes.errors).map(([ref, error]) => ({
+                      message: `Got error: ${error.message} in ${ref}`
+                    }))
+                  }
+                };
+              }
+            }
           }
-          if (remoteFileAuthRes && remoteFileAuthRes.status !== 200) {
-            return remoteFileAuthRes;
+          if (serverOps instanceof ValOpsFS) {
+            var _remoteFileAuthRes;
+            const isRemoteRequired = getIsRemoteRequired(await serverOps.getSchemas());
+            let mode;
+            let remoteFileAuthRes;
+            if (isRemoteRequired) {
+              mode = "upload-remote";
+              remoteFileAuthRes = await getRemoteFileAuth();
+            } else {
+              mode = "skip-remote";
+            }
+            if (remoteFileAuthRes && remoteFileAuthRes.status !== 200) {
+              return remoteFileAuthRes;
+            }
+            const remoteFileAuth = (_remoteFileAuthRes = remoteFileAuthRes) === null || _remoteFileAuthRes === void 0 || (_remoteFileAuthRes = _remoteFileAuthRes.json) === null || _remoteFileAuthRes === void 0 ? void 0 : _remoteFileAuthRes.remoteFileAuth;
+            const saveRes = await serverOps.saveOrUploadFiles(preparedCommit, mode, remoteFileAuth);
+            if (Object.keys(saveRes.errors).length > 0) {
+              console.error("Val: Failed to save files", saveRes.errors);
+              return {
+                status: 400,
+                json: {
+                  message: "Failed to save files",
+                  details: Object.entries(saveRes.errors).map(([key, error]) => {
+                    return {
+                      message: `Got error: ${error} in ${key}`
+                    };
+                  })
+                }
+              };
+            }
           }
-          const remoteFileAuth = (_remoteFileAuthRes = remoteFileAuthRes) === null || _remoteFileAuthRes === void 0 || (_remoteFileAuthRes = _remoteFileAuthRes.json) === null || _remoteFileAuthRes === void 0 ? void 0 : _remoteFileAuthRes.remoteFileAuth;
-          const saveRes = await serverOps.saveOrUploadFiles(preparedCommit, mode, remoteFileAuth);
-          if (Object.keys(saveRes.errors).length > 0) {
-            console.error("Val: Failed to save files", saveRes.errors);
-            return {
-              status: 400,
-              json: {
-                message: "Failed to save files",
-                details: Object.entries(saveRes.errors).map(([key, error]) => {
-                  return {
-                    message: `Got error: ${error} in ${key}`
-                  };
-                })
-              }
-            };
+          /*
+           * The host's destination, after the store's own.
+           *
+           * Ordered this way so a store that writes has already succeeded by
+           * the time the host is told: `commitPrepared` throwing fails the save,
+           * and a host that publishes what it was handed should not be handed
+           * files the store could not write.
+           */
+          if (options.commitPrepared) {
+            await options.commitPrepared({
+              patchedSourceFiles: preparedCommit.patchedSourceFiles
+            });
           }
           /*
            * The files on disk are the committed content now, so say so here too.
@@ -11570,7 +12481,6 @@ const ValServer = (valModules, options, callbacks) => {
           };
         } else if (serverOps instanceof ValOpsHttp) {
           if (auth.error === undefined && auth.id) {
-            var _options$config$files;
             /*
              * The group this commit CLOSES has to be the caller's.
              *
@@ -11610,14 +12520,32 @@ const ValServer = (valModules, options, callbacks) => {
               }
             }
             const message = body.message || "Val CMS update (" + Object.keys(analysis.patchesByModule).length + " files changed)";
-            const commitRes = await serverOps.commit(preparedCommit, message, auth.id, ((_options$config$files = options.config.files) === null || _options$config$files === void 0 ? void 0 : _options$config$files.directory) || "/public/val", undefined,
+            const commitToGit = () => {
+              var _options$config$files;
+              return serverOps.commit(preparedCommit, message, auth.id, ((_options$config$files = options.config.files) === null || _options$config$files === void 0 ? void 0 : _options$config$files.directory) || "/public/val", undefined,
+              /*
+               * Forwarded verbatim, and only the client can decide it: the
+               * content API closes the group it is named without checking
+               * that the commit shipped all of it, and whether it did needs
+               * the patch sets, which live in the browser.
+               */
+              body.patchGroupId);
+            };
             /*
-             * Forwarded verbatim, and only the client can decide it: the
-             * content API closes the group it is named without checking that
-             * the commit shipped all of it, and whether it did needs the
-             * patch sets, which live in the browser.
+             * A host may publish somewhere other than the repository.
+             *
+             * See `publishOverride`. It is handed `commitToGit` rather than
+             * having it skipped, so it can replace the commit or add to it --
+             * and it is the host, not this route, that knows which.
              */
-            body.patchGroupId);
+            const commitRes = options.publishOverride ? await options.publishOverride({
+              patchedSourceFiles: preparedCommit.patchedSourceFiles,
+              preparedCommit,
+              message,
+              authorId: auth.id,
+              patchGroupId: body.patchGroupId,
+              commitToGit
+            }) : await commitToGit();
             if (commitRes.error) {
               console.error("Failed to commit", commitRes.error);
               if ("isNotFastForward" in commitRes && commitRes.isNotFastForward) {
@@ -11764,7 +12692,7 @@ const ValServer = (valModules, options, callbacks) => {
             };
           }
         };
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return execFetch(getProfileAuthHeaders(authData, null, "application/json"));
         }
         if (!options.valSecret) {
@@ -11868,7 +12796,7 @@ const ValServer = (valModules, options, callbacks) => {
             };
           }
         };
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return execFetch(getProfileAuthHeaders(authData, null, "application/json"));
         }
         if (!options.valSecret) {
@@ -11954,7 +12882,7 @@ const ValServer = (valModules, options, callbacks) => {
             };
           }
         };
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return execFetch(getProfileAuthHeaders(authData, null, "application/json"));
         }
         if (!options.valSecret) {
@@ -12062,7 +12990,7 @@ const ValServer = (valModules, options, callbacks) => {
             };
           }
         };
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           return execFetch(getProfileAuthHeaders(authData, null, "application/json"));
         }
         if (!options.valSecret) {
@@ -12109,7 +13037,7 @@ const ValServer = (valModules, options, callbacks) => {
         }
         const authData = authDataRes.json.remoteFileAuth;
         let headers;
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           headers = getProfileAuthHeaders(authData, null, "application/json");
         } else {
           if (!("id" in auth) || !auth.id) {
@@ -12196,6 +13124,11 @@ const ValServer = (valModules, options, callbacks) => {
                 }
               };
             }
+            // Deliberately `ValOpsFS` and not `patchesAreLocal`: this writes
+            // BYTES into a patch directory, which is a thing only the fs store
+            // has. A local store without local binary files (ValOpsMemory, which
+            // uses Val's remote files) skips it, and the draft image is served
+            // from the content host rather than mirrored.
             if (serverOps instanceof ValOpsFS) {
               // Mirror the binaries from the content host into local patch
               // storage so /files?patch_id=... can serve them. Match upstream
@@ -12300,7 +13233,7 @@ const ValServer = (valModules, options, callbacks) => {
         }
         const authData = authDataRes.json.remoteFileAuth;
         let headers;
-        if (serverOps instanceof ValOpsFS) {
+        if (serverOps.patchesAreLocal) {
           headers = getProfileAuthHeaders(authData, null, "application/json");
         } else {
           if (!("id" in auth) || !auth.id) {
@@ -12712,7 +13645,15 @@ chain, deleted, requested) {
  * `undefined` means "apply everything", which is what every caller that does
  * not ask for scoping gets and must keep getting.
  */
-async function resolveOwnPatchScope(serverOps, opts) {
+async function resolveOwnPatchScope(
+/*
+ * `ValOps`, not the two concrete stores: the one thing this needs is whether
+ * a content service holds the groups, and it asks that below with an
+ * `instanceof ValOpsHttp`. Naming the implementations here meant every new
+ * store had to be added to a list to be allowed to call a function that does
+ * not use it.
+ */
+serverOps, opts) {
   let ownPatchIds;
   /** See where this is set: committed work is nobody's to hold back. */
   let scopeAlsoIncludesApplied = false;
@@ -13215,16 +14156,45 @@ function getIsRemoteRequired(schemas) {
   return false;
 }
 
-async function createValServer(valModules, route, opts, config, callbacks, formatter) {
+async function createValServer(valModules, route, opts, config, callbacks, formatter,
+/**
+ * Called after a save has applied its patches. EXPERIMENTAL — see
+ * `ValServerOptions.commitPrepared`.
+ */
+commitPrepared,
+/**
+ * What a publish does in http mode. EXPERIMENTAL — see
+ * `ValServerOptions.publishOverride`.
+ */
+publishOverride) {
   const valServerConfig = await initHandlerOptions(route, opts, config);
   return ValServer(valModules, {
     formatter,
+    commitPrepared,
+    publishOverride,
     ...valServerConfig
   }, callbacks);
 }
 
 // TODO: remove
+/**
+ * `fs` and `path` are imported INSIDE this function, not at the top of the file.
+ *
+ * This is the only thing in this module that touches either, and it is a local
+ * development convenience: scanning upwards for a `.git` to guess the commit and
+ * branch. A static import put `fs` in the module graph of everything reaching
+ * `createValApiRouter` -- which is every server integration, including ones that
+ * run where there is no filesystem. Workerd provides no `fs`, so such a build
+ * could not be bundled at all without stubbing it.
+ *
+ * The `await import` costs nothing here: the only caller is the CLI, on a
+ * machine that has both.
+ */
 async function safeReadGit(cwd) {
+  const {
+    promises: fs
+  } = await import('fs');
+  const path = await import('path');
   async function findGitHead(currentDir, depth) {
     const gitHeadPath = path.join(currentDir, ".git", "HEAD");
     if (depth > 1000) {
@@ -13235,7 +14205,7 @@ async function safeReadGit(cwd) {
       };
     }
     try {
-      const headContents = await promises.readFile(gitHeadPath, "utf-8");
+      const headContents = await fs.readFile(gitHeadPath, "utf-8");
       const match = headContents.match(/^ref: refs\/heads\/(.+)/);
       if (match) {
         const branchName = match[1];
@@ -13272,9 +14242,15 @@ async function safeReadGit(cwd) {
     };
   }
 }
+
+/** Only reached from {@link safeReadGit}; same reason for the local imports. */
 async function readCommit(gitDir, branchName) {
+  const {
+    promises: fs
+  } = await import('fs');
+  const path = await import('path');
   try {
-    return (await promises.readFile(path.join(gitDir, ".git", "refs", "heads", branchName), "utf-8")).trim();
+    return (await fs.readFile(path.join(gitDir, ".git", "refs", "heads", branchName), "utf-8")).trim();
   } catch {
     return undefined;
   }
@@ -15903,4 +16879,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, planJsonValuesEntryExtraction, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };
+export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, InMemoryPatchStore, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValOpsMemory, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, planJsonValuesEntryExtraction, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };