@valbuild/server 0.121.0 → 0.122.0

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

@@ -599,11 +599,13 @@ const patchValFile = async (id, rootDir, patch$1, sourceFileHandler) => {
     // );
     // sourceFileHandler.moveFile(tempFilePath, "." + filePath);
     // TODO: ensure that directory exists
-    if (content.startsWith("data:/image/svg+xml")) {
-      sourceFileHandler.writeFile("." + filePath, convertDataUrlToBase64(content).toString("utf8"), "utf8");
-    } else {
-      sourceFileHandler.writeFile("." + filePath, convertDataUrlToBase64(content).toString("binary"), "binary");
-    }
+    // NOTE: there used to be a branch here testing
+    // `content.startsWith("data:/image/svg+xml")` - with a stray slash after
+    // `data:`, so it could never match a real data URL and SVGs took the
+    // "binary" path anyway. Removed rather than fixed: the branch existed to
+    // write SVG as utf8, and writing the decoded bytes is correct for every
+    // type including SVG.
+    sourceFileHandler.writeFile("." + filePath, convertDataUrlToBase64(content).toString("binary"), "binary");
   }
   sourceFileHandler.writeSourceFile(newSourceFile.value);
   // console.timeEnd("patchValFile" + timeId);
@@ -1952,6 +1954,183 @@ class Service {
   }
 }
 
+/**
+ * The type surface of an external record's adapter.
+ *
+ * Nothing here runs: phase 0 is the contract, and the registry that executes it
+ * arrives with the read endpoints. What the contract has to get right now is the
+ * shape, because every adapter written against it is a compatibility promise.
+ *
+ * Four kinds of method, and each is required or not for one reason:
+ *
+ * - **Read** — `keys`, `get`. Cannot be built out of anything else, so always
+ *   required.
+ * - **Write** — `put`, `delete`. Likewise, and they move together: required on a
+ *   writable record, forbidden on a `.readonly()` one.
+ * - **Derived** — `count`, `search`. Computable from the read methods, so
+ *   omitting one costs performance, never capability. `false` declines the
+ *   fallback; that is the only thing `false` ever means here.
+ * - **Media** — `putFile`, `getFile`. A pair, and required by the item SCHEMA
+ *   rather than by this type (see `hasMediaSchema`).
+ */
+
+// #region result
+
+/**
+ * Brands the result envelope so a bare value can be accepted alongside it.
+ *
+ * A symbol rather than a property name because `get` returns
+ * `Record<key, Item>` — a record that can perfectly well contain a key called
+ * `kind`. The envelope never crosses the wire (it travels in-process between
+ * adapter and Val), so there is no serialization cost to it.
+ */
+const EXTERNAL_RESULT = Symbol.for("@valbuild/server/ExternalResult");
+
+/**
+ * What every adapter method may return: the value on its own, or the envelope.
+ *
+ * A bare value means "ok, nothing to report", which keeps the common path one
+ * line. Errors can be thrown instead of returned — the envelope is for a failure
+ * worth classifying, or a success worth annotating.
+ */
+
+/**
+ * Wrap a value as a successful result, optionally with warnings.
+ *
+ * `NoInfer` is load-bearing, not decoration. Without it `T` is inferred FROM the
+ * argument, and an object literal that infers its own type is not contextually
+ * typed by the adapter's contract — so `title` inside `ok({ a: { title } })` is a
+ * fresh property that happens to be named `title`, with no declaration link back
+ * to `title: s.string()` in the schema. "Find all references" on the schema field
+ * then stops at the page that reads it and never reaches the adapter that
+ * produces it. `NoInfer` blocks that inference, leaving the contextual return
+ * type as the only source for `T`, which is what restores the link (and, as a
+ * bonus, makes a typo report the offending property rather than the whole
+ * return value).
+ *
+ * `externalNavigation.test.ts` guards this; nothing else would notice.
+ *
+ * The cost: `ok(...)` in a position with NO contextual type — a helper without a
+ * return type annotation — infers `unknown` instead of the argument's type, and
+ * fails where the helper is used rather than where it is written. Annotate the
+ * helper's return type, or inline it.
+ */
+function ok$1(value, warnings) {
+  return warnings && warnings.length > 0 ? {
+    [EXTERNAL_RESULT]: true,
+    kind: "ok",
+    value,
+    warnings
+  } : {
+    [EXTERNAL_RESULT]: true,
+    kind: "ok",
+    value
+  };
+}
+function err$1(issue) {
+  return {
+    [EXTERNAL_RESULT]: true,
+    kind: "err",
+    error: issue
+  };
+}
+function isExternalResult(value) {
+  return typeof value === "object" && value !== null && value[EXTERNAL_RESULT] === true;
+}
+
+// #endregion
+
+// #region context
+
+/**
+ * What every adapter method is told about the call it is serving.
+ *
+ * `tx` is present only when the adapter declared an `around`; a store with no
+ * transaction seam has nothing to put there and nothing to ignore.
+ */
+
+// #endregion
+
+// #region paging, sorting, searching
+
+/**
+ * How a page should be ordered.
+ *
+ * Records are unordered today and sorting is coming; the parameter lands now
+ * because adding one to `keys` later would break every adapter that exists by
+ * then. Val passes `undefined` until sorting ships, and an adapter may ignore it.
+ *
+ * Two rules for whoever implements it:
+ *
+ * - **A cursor is only valid for the sort that issued it.** Key-ordered paging
+ *   is `where key > cursor`; sorted paging is `where (field, key) > (…, …)`.
+ *   Val pairs the cursor with a hash of the sort and restarts rather than
+ *   replaying a mismatched one.
+ * - **The key is always the last sort term.** Ordering by a non-unique field
+ *   without a tiebreaker lets rows shift between pages, so page 2 can skip or
+ *   repeat an entry while both pages look fine on their own.
+ */
+
+// #endregion
+
+// #region media
+
+// #endregion
+
+// #region the adapter
+
+/** Read methods. Always required. */
+
+/**
+ * Write methods. Required together, and forbidden together on `.readonly()`.
+ *
+ * `put` must be an UPSERT keyed by the entry key and `delete` must tolerate an
+ * absent key, because a publish may be replayed: retry re-runs the whole scope
+ * where there is a transaction, and the individual call where there is not.
+ */
+
+/**
+ * Named so the compiler prints the reason. A bare `never` would report only
+ * "not assignable to type 'undefined'", which tells nobody anything.
+ */
+
+/** Derived and media methods, and the sort declaration. */
+
+/** The item type an external module's entries hold, loosened as JSON allows. */
+
+/**
+ * The adapter a given external module needs.
+ *
+ * Writes are required or forbidden by the module's own `.readonly()`, read off
+ * the source marker's phantom.
+ */
+
+/** What `entry()` returns: a module and its adapter, checked against each other. */
+
+/**
+ * Declare the adapters for this project's external records.
+ *
+ * `Tx` is given explicitly: `around` offers the compiler no inference site,
+ * since `run` is a callback you CALL rather than one whose signature you write.
+ * One type argument, in one place, and every inline adapter then gets `tx`,
+ * `cursor`, `limit` and the row shape correctly typed.
+ *
+ * @example
+ * const { entry, modules } = defineExternal<typeof sql>({
+ *   around: (run) => sql.begin(run),
+ * });
+ *
+ * export default modules({
+ *   posts: entry(postsVal, { keys, get, put, delete: del, search: false }),
+ * });
+ *
+ * @example a store with no transaction
+ * const { entry, modules } = defineExternal();
+ */
+function defineExternal(definition) {
+  throw new Error("defineExternal is not implemented yet: phase 0 lands the contract, the registry that executes it arrives with the read endpoints.");
+}
+
 const JwtPayloadSchema = z.z.object({
   sub: z.z.string(),
   exp: z.z.number(),
@@ -3736,6 +3915,47 @@ class ValOps {
         };
       }
     }));
+
+    /*
+     * What each changed module IS after this commit, and the schema it is under.
+     *
+     * The data rather than the file's text, because that is the half git cannot
+     * give back: a `.val.ts` in git is code, and turning code back into data
+     * means parsing it, which is best-effort and rots across TypeScript,
+     * runtime and Val versions. The schema comes along because a value on its
+     * own cannot be RENDERED - showing a module as it was at a commit whose
+     * schema has since changed needs the schema of that commit, and nothing in
+     * the current checkout has it.
+     *
+     * Taken from `getSources(analysis)` rather than re-derived here so the data
+     * stored is the same data the Studio shows, produced by the one
+     * implementation of "apply these ops".
+     */
+    const moduleVersions = {};
+    const {
+      sources: sourcesAfter
+    } = await this.getSources(patchAnalysis);
+    for (const path of Object.keys(patchesByModule)) {
+      let serialized;
+      try {
+        var _schemas$path3;
+        serialized = (_schemas$path3 = schemas[path]) === null || _schemas$path3 === void 0 ? void 0 : _schemas$path3["executeSerialize"]();
+      } catch {
+        // Same guard as above: one unserializable schema must not cost every
+        // other module its history.
+        serialized = undefined;
+      }
+      if (!serialized) {
+        continue;
+      }
+      const source = sourcesAfter[path];
+      moduleVersions[path] = {
+        // `undefined` here means the module is gone, which is a state history
+        // has to be able to show. `null` is how that travels over the wire.
+        source: source === undefined ? null : source,
+        schema: serialized
+      };
+    }
     const res = {
       hasErrors,
       sourceFilePatchErrors,
@@ -3748,7 +3968,8 @@ class ValOps {
       patchedBinaryFilesDescriptors,
       appliedPatches,
       skippedPatches,
-      triedPatches
+      triedPatches,
+      moduleVersions
     };
     return res;
   }
@@ -3805,6 +4026,66 @@ class ValOps {
   }
 
   // #region abstract ops
+
+  /**
+   * Save a patch's binary file from a `data:...;base64,...` URL.
+   *
+   * The wire form: `FileReader.readAsDataURL` is what the browser produces, and
+   * published `@valbuild/server` versions send it. Code that already HAS bytes
+   * should call {@link saveBinaryFileFromPatch} instead of wrapping them in a
+   * data URL just to have this unwrap them again.
+   *
+   * A `null` `data` records a DELETION, which is why this cannot simply be
+   * replaced by the byte-taking sibling: there is nothing to hand it.
+   */
+
+  /**
+   * The same, for a caller that already has the bytes.
+   *
+   * Default implementation wraps them back into a data URL so every backend
+   * gets this for free; a backend that can take bytes straight through should
+   * override it.
+   */
+  async saveBinaryFileFromPatch(filePath, parentRef, patchId, bytes, mimeType, type, metadata) {
+    return this.saveBase64EncodedBinaryFileFromPatch(filePath, parentRef, patchId, `data:${mimeType};base64,${bytes.toString("base64")}`, type, metadata);
+  }
+
+  // #region history
+  //
+  // Reading the past, as opposed to reading the present with pending patches
+  // applied. Every one of these is Result-typed against `HistoryError`, because
+  // the ways this can fail - an unreadable record, a source that no longer
+  // parses, an op that will not replay, a schema that has moved on - are the
+  // interesting part rather than an edge case, and a caller deciding whether to
+  // offer a RESTORE has to know which one it hit.
+  //
+  // Only implemented where there is a service holding the history:
+  // `ValOpsHttp`. `ValOpsFS` answers `not-supported-in-fs-mode`, because local
+  // dev has git for this and no commit records of its own.
+
+  /** One page of a branch's commits, newest first. See history/listCommits. */
+
+  /** The patches that produced one commit, with their ops. */
+
+  /**
+   * How each `.val.ts` the commit changed looked BEFORE it, keyed by module
+   * file path. Empty for a commit made before this was recorded - which the
+   * caller reports as `source-unavailable` rather than as an empty module.
+   */
+  /**
+   * Each module a commit changed: its data, and the schema it was under.
+   *
+   * `asOf` widens it from "what this commit changed" to "the whole project as
+   * this commit left it", which is what reverting everything to a point in time
+   * needs; `moduleFilePath` narrows it to one module, for navigating the
+   * history pane off the changed set.
+   */
+
+  /** Which files the commit touched, and how. Names them; does not fetch them. */
+
+  /** One file's bytes as they were at one commit. */
+
+  // #endregion history
 }
 function isOnlyFileCheckValidationError(validationError) {
   var _validationError$fixe9;
@@ -6410,6 +6691,46 @@ class ValOpsFS extends ValOps {
   getPatchLockFile() {
     return path__namespace["default"].join(this.rootDir, ValOpsFS.VAL_DIR, PATCH_LOCK_FILE_NAME);
   }
+
+  // #region history
+  //
+  // Not available locally, and deliberately not faked from git.
+  //
+  // History is a record of what VAL did: which patches produced a commit, who
+  // wrote them, and what each module looked like immediately before. Git has
+  // the files but not that - it cannot say which of a commit's changes were one
+  // editor's patch set, so a "restore this change" built on it would be
+  // guesswork wearing the same UI.
+  //
+  // A single, honest error rather than five different ones: the caller's
+  // question is "is history available here", and the answer is no.
+
+  async listCommits() {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getCommitPatches() {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getCommitModules() {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getCommitAffectedFiles() {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  async getFileAtCommit() {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
+  // #endregion history
 }
 class FSOpsHost {
   constructor() {}
@@ -6697,6 +7018,99 @@ const CommitResponse = z.z.object({
   commit: CommitSha,
   branch: z.z.string()
 });
+// #region history wire schemas
+//
+// Validated on arrival rather than trusted: these come from a service that
+// versions separately, and a silently mis-shaped commit record reads as "this
+// commit changed nothing", which is indistinguishable from a real answer.
+const HistoricalCommitResponse = z.z.object({
+  commitSha: z.z.string(),
+  parentCommitSha: z.z.string(),
+  clientCommitSha: z.z.string(),
+  branch: z.z.string(),
+  createdBranch: z.z.string().nullable(),
+  creator: z.z.string().nullable(),
+  message: z.z.string().nullable(),
+  createdAt: z.z.string(),
+  seqNum: z.z.string(),
+  patchCount: z.z.number(),
+  hasArchive: z.z.boolean()
+});
+const ListCommitsResponse = z.z.object({
+  commits: z.z.array(HistoricalCommitResponse),
+  nextCursor: z.z.string().nullable()
+});
+const CommitPatchesResponse = z.z.object({
+  commitSha: z.z.string(),
+  commit: z.z.object({
+    commitSha: z.z.string(),
+    parentCommitSha: z.z.string(),
+    clientCommitSha: z.z.string(),
+    branch: z.z.string(),
+    createdBranch: z.z.string().nullable(),
+    creator: z.z.string().nullable(),
+    message: z.z.string().nullable(),
+    createdAt: z.z.string(),
+    seqNum: z.z.string(),
+    hasArchive: z.z.boolean()
+  }),
+  patches: z.z.array(z.z.object({
+    patchId: z.z.string(),
+    path: z.z.string(),
+    patch: z.z.unknown(),
+    authorId: z.z.string().nullable(),
+    createdAt: z.z.string(),
+    baseSha: z.z.string(),
+    coreVersion: z.z.string()
+  }))
+});
+
+/**
+ * `home` — `Api["/commits/:commitSha/modules"]["GET"]["res"]`.
+ *
+ * `schema` stays `unknown` here on purpose. The content service stores it
+ * opaquely and cannot vouch for it, so validating it at the transport boundary
+ * would turn "a schema written by a different version of Val" into a failed
+ * REQUEST rather than one module that cannot be shown. It is checked in
+ * `getHistoricalPatchSet`, per module, where a failure degrades that module and
+ * leaves the commit readable.
+ */
+const CommitModulesResponse = z.z.object({
+  commitSha: z.z.string(),
+  parentCommitSha: z.z.string(),
+  /**
+   * Whether an `asOf` read covered the whole project.
+   *
+   * Optional so an older content server still parses. False means modules last
+   * edited before history started being recorded are missing from the answer -
+   * which a whole-project revert has to say out loud rather than silently skip.
+   */
+  complete: z.z.boolean().optional(),
+  modules: z.z.array(z.z.object({
+    moduleFilePath: z.z.string(),
+    commitSha: z.z.string(),
+    sourceSha: z.z.string().nullable(),
+    schemaSha: z.z.string(),
+    // Validated, because a Source IS just JSON and this side knows that much.
+    source: internal.JSONValue.nullable(),
+    schema: z.z.unknown(),
+    unavailable: z.z.boolean()
+  }))
+});
+const CommitAffectedFilesResponse = z.z.object({
+  commitSha: z.z.string(),
+  files: z.z.array(z.z.union([z.z.object({
+    kind: z.z.union([z.z.literal("module-source"), z.z.literal("json-entry"), z.z.literal("binary")]),
+    gitPath: z.z.string(),
+    change: z.z.union([z.z.literal("added"), z.z.literal("modified"), z.z.literal("deleted")])
+  }), z.z.object({
+    kind: z.z.literal("remote-binary"),
+    ref: z.z.string(),
+    change: z.z.union([z.z.literal("added"), z.z.literal("modified"), z.z.literal("deleted")])
+  })]))
+});
+// #endregion history wire schemas
+
 /*
  * The shared schema, not a copy of it.
  *
@@ -7716,7 +8130,12 @@ class ValOpsHttp extends ValOps {
     if (!file) {
       return null;
     }
-    return bufferFromDataUrl(file.value) ?? null;
+    // Plain base64, the same as the `repo` branch of getBinaryFile above.
+    //
+    // `value` used to be a data: URL here and plain base64 there - two
+    // encodings in one field, told apart only by which branch produced them.
+    // The content service answers base64 for both now.
+    return Buffer.from(file.value, "base64");
   }
   async getBase64EncodedBinaryFileMetadataFromPatch(filePath, type, patchId, remote) {
     const params = new URLSearchParams();
@@ -7885,6 +8304,19 @@ class ValOpsHttp extends ValOps {
           patchedSourceFiles: prepared.patchedSourceFiles,
           patchedBinaryFilesDescriptors: prepared.patchedBinaryFilesDescriptors,
           appliedPatches: prepared.appliedPatches,
+          /*
+           * What each changed module IS after this commit, as DATA, with the
+           * schema it is under.
+           *
+           * The half git cannot give back. Git keeps the `.val.ts`, but that is
+           * code: turning it back into data means parsing it, which is
+           * best-effort and rots across TypeScript, runtime and Val versions -
+           * so a commit that reads today can quietly stop reading later. And
+           * git has no copy at all of the SCHEMA a commit was written under,
+           * which is what showing a module as it was needs once the schema has
+           * moved on.
+           */
+          modules: prepared.moduleVersions,
           commit: this.commitSha,
           root: this.root,
           filesDirectory,
@@ -7945,80 +8377,681 @@ class ValOpsHttp extends ValOps {
       };
     }
   }
-}
 
-const host = process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
-const SettingsSchema = z.z.object({
-  publicProjectId: z.z.string(),
-  remoteFileBuckets: z.z.array(z.z.object({
-    bucket: z.z.string()
-  }))
-});
-async function getSettings(projectName, auth) {
-  try {
-    const response = await fetch(`${host}/v1/${projectName}/settings`, {
-      headers: "pat" in auth ? {
-        "x-val-pat": auth.pat,
-        "Content-Type": "application/json"
-      } : {
-        Authorization: `Bearer ${auth.apiKey}`,
-        "Content-Type": "application/json"
+  // #region history
+
+  /**
+   * One GET against the content service, parsed and Result-typed.
+   *
+   * Every history read has the same three failure modes - could not reach the
+   * service, the commit is not there, the answer was not what was expected -
+   * and each of them means something different to a caller deciding whether to
+   * offer a restore. Doing it once here is what keeps that consistent across
+   * the five endpoints.
+   */
+  async getHistory(path, schema, commitShaForErrors) {
+    let res;
+    try {
+      res = await fetch(`${this.contentUrl}/v1/${this.project}${path}`, {
+        headers: {
+          ...this.authHeaders,
+          "Content-Type": "application/json"
+        }
+      });
+    } catch (err) {
+      return fp.result.err({
+        kind: "transport",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    if (res.status === 404) {
+      return fp.result.err({
+        kind: "commit-not-found",
+        commitSha: commitShaForErrors
+      });
+    }
+    if (!res.ok) {
+      var _res$headers$get4;
+      let message = `${res.status} ${res.statusText}`;
+      if ((_res$headers$get4 = res.headers.get("Content-Type")) !== null && _res$headers$get4 !== void 0 && _res$headers$get4.includes("application/json")) {
+        message = internal.getErrorMessageFromUnknownJson(await res.json(), message);
       }
+      // A 5xx from the service reading a record it says it has is a real
+      // failure of that record, not a network problem - keep them apart.
+      return fp.result.err({
+        kind: "archive-unreadable",
+        commitSha: commitShaForErrors,
+        message
+      });
+    }
+    // A 200 is not a promise of JSON: a proxy or gateway in front of the
+    // service answers HTML, and an unguarded `.json()` would reject straight
+    // out of this Result-typed API and 500 the route.
+    let body;
+    try {
+      body = await res.json();
+    } catch (err) {
+      return fp.result.err({
+        kind: "archive-unreadable",
+        commitSha: commitShaForErrors,
+        message: `response was not JSON: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+    const parsed = schema.safeParse(body);
+    if (!parsed.success) {
+      return fp.result.err({
+        kind: "archive-unreadable",
+        commitSha: commitShaForErrors,
+        message: `unexpected response shape: ${zodValidationError.fromError(parsed.error)}`
+      });
+    }
+    return fp.result.ok(parsed.data);
+  }
+  async listCommits(branch, options) {
+    const params = new URLSearchParams({
+      branch
     });
-    if (response.status === 404) {
-      return {
-        success: false,
-        message: `Project '${projectName}' not found: verify that the name of the project is correct and that you have access to it.`
-      };
+    if ((options === null || options === void 0 ? void 0 : options.limit) !== undefined) {
+      params.set("limit", String(options.limit));
     }
-    if (response.status !== 200) {
-      return {
-        success: false,
-        message: `Failed to get project id: ${response.statusText}`
-      };
+    if ((options === null || options === void 0 ? void 0 : options.cursor) !== undefined) {
+      params.set("cursor", options.cursor);
     }
-    const json = await response.json();
-    const parseRes = SettingsSchema.safeParse(json);
-    if (!parseRes.success) {
-      return {
-        success: false,
-        message: `Failed to parse settings data: ${parseRes.error.message}`
-      };
+    const res = await this.getHistory(`/commits?${params}`, ListCommitsResponse, branch);
+    if (fp.result.isErr(res)) {
+      return res;
     }
-    return {
-      success: true,
-      data: parseRes.data
-    };
-  } catch {
-    return {
-      success: false,
-      message: `Failed to get project id. Check network connection and try again.`
-    };
+    return fp.result.ok({
+      commits: res.value.commits,
+      nextCursor: res.value.nextCursor
+    });
   }
-}
-
-/**
- * Resolving how Val is configured, and building the data layer from it.
- *
- * Both live here rather than inside `createValApiRouter` because the MCP tool
- * registry needs exactly the same answers: which mode we are in, which
- * credential to use, and which `ValOps` implementation that implies. Two copies
- * of this would drift, and the failure would be quiet — a registry that decides
- * it is in fs mode while the Studio decides it is in proxy mode reads different
- * content from the same project.
- *
- * The type-only import from `./ValRouter` is deliberate: it keeps `ValApiOptions`
- * where its documentation lives without creating a runtime cycle.
- *
- * The credential-bearing URL check at the bottom of this file lives here for the
- * same reason: it is a check on the URLs `initHandlerOptions` resolves, and its
- * only caller is that function. Leaving it in `./ValRouter` would have meant
- * importing it back from there, which is the runtime cycle the paragraph above
- * exists to avoid.
- */
-
-const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
-
+  async getCommitPatches(commitSha) {
+    // One request. The endpoint returns the commit's own summary alongside its
+    // patches, because it already has the row - this used to page the commit
+    // LISTING until the sha turned up, which cost up to twenty requests to open
+    // an old commit and could not find one on another branch at all.
+    const patchesRes = await this.getHistory(`/commits/${commitSha}/patches`, CommitPatchesResponse, commitSha);
+    if (fp.result.isErr(patchesRes)) {
+      return patchesRes;
+    }
+    return fp.result.ok({
+      commit: {
+        ...patchesRes.value.commit,
+        patchCount: patchesRes.value.patches.length
+      },
+      patches: patchesRes.value.patches.map(patch => ({
+        patchId: patch.patchId,
+        moduleFilePath: patch.path,
+        patch: patch.patch,
+        authorId: patch.authorId,
+        createdAt: patch.createdAt,
+        baseSha: patch.baseSha,
+        coreVersion: patch.coreVersion
+      }))
+    });
+  }
+  async getCommitModules(commitSha, options) {
+    const query = new URLSearchParams();
+    if (options !== null && options !== void 0 && options.asOf) {
+      query.set("as_of", "1");
+    }
+    if (options !== null && options !== void 0 && options.moduleFilePath) {
+      query.set("path", options.moduleFilePath);
+    }
+    const search = query.toString();
+    const res = await this.getHistory(`/commits/${commitSha}/modules${search ? `?${search}` : ""}`, CommitModulesResponse, commitSha);
+    if (fp.result.isErr(res)) {
+      return res;
+    }
+    return fp.result.ok({
+      modules: res.value.modules.map(module => ({
+        ...module,
+        moduleFilePath: module.moduleFilePath
+      })),
+      // Absent from an older content server, which only ever answered "what
+      // this commit changed" - and that answer is always whole.
+      complete: res.value.complete ?? !(options !== null && options !== void 0 && options.asOf)
+    });
+  }
+  async getCommitAffectedFiles(commitSha) {
+    const res = await this.getHistory(`/commits/${commitSha}/affected-files`, CommitAffectedFilesResponse, commitSha);
+    if (fp.result.isErr(res)) {
+      return res;
+    }
+    return fp.result.ok(res.value.files);
+  }
+  async getFileAtCommit(commitSha, filePath, remote) {
+    const params = new URLSearchParams({
+      path: filePath
+    });
+    if (remote) {
+      params.set("remote", "true");
+    }
+    let res;
+    try {
+      res = await fetch(`${this.contentUrl}/v1/${this.project}/commits/${commitSha}/file?${params}`, {
+        headers: {
+          ...this.authHeaders
+        }
+      });
+    } catch (err) {
+      return fp.result.err({
+        kind: "transport",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    if (!res.ok) {
+      // A missing file is about the FILE, not the commit: the commit may be
+      // perfectly readable and this one blob gone. Saying "commit not found"
+      // here would send a caller looking in the wrong place.
+      return fp.result.err({
+        kind: "file-unavailable",
+        gitPath: filePath,
+        message: `${res.status} ${res.statusText}`
+      });
+    }
+    return fp.result.ok(Buffer.from(await res.arrayBuffer()));
+  }
+  // #endregion history
+}
+
+/**
+ * Everything that can go wrong reading, replaying or restoring history.
+ *
+ * There is a lot of it, which is the point of making it one closed union rather
+ * than strings: reading a commit means reaching a content host, finding the
+ * commit, reading what was recorded for each of its modules, and asking whether
+ * this version of Val can make sense of the schema it was stored under. Each of
+ * those fails differently, and a caller deciding what to SHOW needs to know
+ * which.
+ *
+ * Every member has a producer. The union once carried five more - a module
+ * removed from the project, an op that would not replay, a value that no longer
+ * fits today's schema, a field the schema no longer defines, and ops from a
+ * core version known to replay wrongly. All five belonged to reconstructing a
+ * commit by replaying patches against a parsed source; storing the data ended
+ * that, and a member nothing can produce is a state the Studio writes handling
+ * for and never sees.
+ *
+ * ## The rule
+ *
+ * Whole-commit failures are the `err` channel. Per-module and per-patch
+ * failures ride along inside the `ok` payload.
+ *
+ * A commit that cannot be found or read at all has nothing to show. But one
+ * unparseable module out of ten does not make the other nine unreadable, and
+ * collapsing the whole view because of it would hide exactly the information
+ * someone needs to see - that this module is the broken one.
+ */
+
+function historyErrorMessage(error) {
+  switch (error.kind) {
+    case "commit-not-found":
+      return `No commit ${error.commitSha} created by Val in this project`;
+    case "archive-unreadable":
+      return `Could not read the stored record of commit ${error.commitSha}: ${error.message}`;
+    case "source-unavailable":
+      return `No stored source for ${error.moduleFilePath} at this commit (it predates history being recorded)`;
+    case "schema-unreadable":
+      return `The schema stored for ${error.moduleFilePath} at this commit is not one this version of Val can read: ${error.message}`;
+    case "file-unavailable":
+      return `Could not read ${error.gitPath} at this commit: ${error.message}`;
+    case "not-supported-in-fs-mode":
+      return "History is only available for projects connected to Val's content service";
+    case "transport":
+      return `Could not reach the content service: ${error.message}`;
+  }
+}
+
+/**
+ * Everything the content service knows about one commit, in one step.
+ *
+ * Three endpoints, requested together rather than in sequence: they are
+ * independent, they all resolve from the same stored record, and the round
+ * trips are what a user waits through when opening a commit.
+ *
+ * The commit itself comes from the patches call, which is the one that fails
+ * usefully when the commit does not exist.
+ */
+async function fetchCommitRecord(ops, commitSha) {
+  const [patchesRes, modulesRes, filesRes] = await Promise.all([ops.getCommitPatches(commitSha), ops.getCommitModules(commitSha), ops.getCommitAffectedFiles(commitSha)]);
+  if (fp.result.isErr(patchesRes)) {
+    return patchesRes;
+  }
+  if (fp.result.isErr(modulesRes)) {
+    return modulesRes;
+  }
+  if (fp.result.isErr(filesRes)) {
+    return filesRes;
+  }
+  return fp.result.ok({
+    commit: patchesRes.value.commit,
+    patches: patchesRes.value.patches,
+    modules: modulesRes.value.modules,
+    affectedFiles: filesRes.value
+  });
+}
+
+/**
+ * The `*.val.json` entries a commit touched, read from git at that commit.
+ *
+ * Not stored in the commit record, unlike the `.val.ts` sources: an entry is a
+ * plain JSON file that git has at every commit, so a second copy could only
+ * drift from the first. A `.val.ts` is different - it is what a restore
+ * replays patches against, and reading it from git would make every look at
+ * history depend on the repository still being there.
+ *
+ * Reads at the commit itself rather than its parent: an entry's content AT a
+ * commit is what that commit produced, which is the "after" side. The "before"
+ * side is the same file at the parent commit, and a caller that wants it asks
+ * for the parent.
+ */
+async function resolveJsonEntriesAtCommit(ops, commitSha, affectedFiles) {
+  const entryPaths = affectedFiles.filter(file => file.kind === "json-entry")
+  // A deleted entry has no content at this commit; asking for it would be a
+  // guaranteed 404 reported as a failure, which is noise rather than news.
+  .filter(file => file.change !== "deleted").map(file => file.gitPath);
+  if (entryPaths.length === 0) {
+    return fp.result.ok({
+      entries: {},
+      failures: []
+    });
+  }
+  const entries = {};
+  const failures = [];
+  const fetched = await Promise.all(entryPaths.map(async gitPath => ({
+    gitPath,
+    res: await ops.getFileAtCommit(commitSha, gitPath, false)
+  })));
+  for (const {
+    gitPath,
+    res
+  } of fetched) {
+    if (fp.result.isErr(res)) {
+      failures.push({
+        kind: "file-unavailable",
+        gitPath,
+        message: res.error.kind === "file-unavailable" ? res.error.message : `could not read entry: ${res.error.kind}`
+      });
+      continue;
+    }
+    try {
+      entries[gitPath] = JSON.parse(res.value.toString("utf-8"));
+    } catch (err) {
+      failures.push({
+        kind: "file-unavailable",
+        gitPath,
+        message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  }
+  return fp.result.ok({
+    entries,
+    failures
+  });
+}
+
+/**
+ * Turn a commit's binary files into descriptors, WITHOUT fetching any of them.
+ *
+ * Pure, and that is the whole design. Showing that a commit changed six images
+ * needs six rows, not six downloads; only an `<img>` that actually mounts pays
+ * for its bytes. `url` points at the app's own history file route, which is
+ * immutable for a given commit, so the browser's HTTP cache handles flipping
+ * between commits with no JS cache at all.
+ */
+function describeBinaryFilesAtCommit(commitSha, affectedFiles, /** Where the app serves `/api/val` from, e.g. "/api/val". */
+apiBasePath) {
+  const refs = [];
+  for (const file of affectedFiles) {
+    if (file.kind === "remote-binary") {
+      refs.push({
+        gitPath: file.ref,
+        change: file.change,
+        remote: true,
+        url: historyFileUrl(apiBasePath, commitSha, file.ref, true)
+      });
+      continue;
+    }
+    if (file.kind !== "binary") {
+      continue;
+    }
+    refs.push({
+      gitPath: file.gitPath,
+      change: file.change,
+      remote: false,
+      url: historyFileUrl(apiBasePath, commitSha, file.gitPath, false)
+    });
+  }
+  return refs;
+}
+function historyFileUrl(apiBasePath, commitSha, filePath, remote) {
+  const params = new URLSearchParams({
+    commit_sha: commitSha,
+    path: filePath
+  });
+  if (remote) {
+    params.set("remote", "true");
+  }
+  return `${apiBasePath}/history/files?${params.toString()}`;
+}
+
+/**
+ * The paths a commit's ops touched, from the ops themselves.
+ *
+ * The alternative was reconstructing the module's previous state and diffing it
+ * against the new one - which needed the pre-commit `.val.ts`, a static parse
+ * of it, and a replay of every op, three fragile steps to rediscover something
+ * the ops already say outright. An op carries the path it applies to. That is
+ * the answer.
+ *
+ * Deduplicated and returned in first-touched order, because a module edited
+ * eight times in one publish should list a field once, where it first changed.
+ */
+function changedPathsOf(moduleFilePath, patches) {
+  const seen = new Set();
+  const paths = [];
+  for (const {
+    patch
+  } of patches) {
+    for (const op of patch) {
+      // A `file` op names a file, not a place in the source; the `replace` that
+      // points the field at it is in the same patch and is the real change.
+      if (op.op === "file") {
+        continue;
+      }
+      /*
+       * The canonical patch-path-to-source-path conversion, not a hand-rolled
+       * join.
+       *
+       * `createValPathOfItem` JSON-quotes the ONE key it is handed, so joining
+       * the segments with "." first produced `?p="teddy.name"` — a single
+       * segment with a dot in its name — rather than `?p="teddy"."name"`. Only
+       * top-level fields came out right, a record key containing a dot was
+       * split in the other direction, and an op at the module root became
+       * `?p=""`.
+       *
+       * `patchPathToModulePath` is what the rest of the Studio produces and
+       * parses, integer segments left unquoted (`"items".2."label"`).
+       */
+      const sourcePath = op.path.length === 0 ? moduleFilePath : core.Internal.joinModuleFilePathAndModulePath(moduleFilePath, core.Internal.patchPathToModulePath(op.path));
+      if (!seen.has(sourcePath)) {
+        seen.add(sourcePath);
+        paths.push(sourcePath);
+      }
+    }
+  }
+  return paths;
+}
+
+/**
+ * Reconstruct one commit: how each module looked before it, and after it.
+ *
+ * Deliberately says NOTHING about the current source or the current schema. For
+ * a given commit sha this can never change, which is what lets its result be
+ * cached forever and what makes flipping between commits cheap. The comparison
+ * against today is `compareWithCurrent`, and it is deliberately the cheap half.
+ *
+ * Nothing is parsed and nothing is replayed: the module's data was recorded at
+ * the commit, so reading it back is a read. What IS done here is validating the
+ * stored schema against this version of Val, because that is the one thing the
+ * content service could not check for us.
+ *
+ * Failures are collected per module, not thrown - one module this Val cannot
+ * read leaves the other nine readable, and knowing WHICH one is the thing
+ * someone opening history actually needs. Only a commit that cannot be read at
+ * all is an `err`.
+ */
+async function getHistoricalPatchSet(ops, commitSha, options) {
+  const recordRes = await fetchCommitRecord(ops, commitSha);
+  if (fp.result.isErr(recordRes)) {
+    return recordRes;
+  }
+  const {
+    commit,
+    patches,
+    modules: stored,
+    affectedFiles
+  } = recordRes.value;
+  const warnings = [];
+
+  // Group the commit's patches by module. Not to replay them - the stored
+  // source already IS the result - but because the ops name the paths this
+  // commit touched, which is what the view highlights.
+  const patchesByModule = new Map();
+  for (const patch of patches) {
+    const existing = patchesByModule.get(patch.moduleFilePath) ?? [];
+    existing.push({
+      patchId: patch.patchId,
+      coreVersion: patch.coreVersion,
+      // The wire type is `unknown` because the content service does not know
+      // Val's patch type; it has been validated on the way out of the archive.
+      patch: patch.patch
+    });
+    patchesByModule.set(patch.moduleFilePath, existing);
+  }
+  const storedByPath = new Map(stored.map(module => [module.moduleFilePath, module]));
+
+  // Every module this commit touched: one it patched, and one we hold a stored
+  // version of. Usually the same set - but a commit made by a Val too old to
+  // send its modules has the first and not the second, and that has to read as
+  // `source-unavailable` rather than as "no modules changed".
+  const touched = new Set([...patchesByModule.keys(), ...storedByPath.keys()]);
+  const modules = {};
+  for (const moduleFilePath of touched) {
+    const failures = [];
+    const modulePatches = patchesByModule.get(moduleFilePath) ?? [];
+    const patchIds = modulePatches.map(patch => patch.patchId);
+    const changedPaths = changedPathsOf(moduleFilePath, modulePatches);
+    const version = storedByPath.get(moduleFilePath);
+    if (version === undefined || version.unavailable) {
+      failures.push({
+        kind: "source-unavailable",
+        moduleFilePath
+      });
+      modules[moduleFilePath] = {
+        source: null,
+        schema: null,
+        patchIds,
+        changedPaths,
+        failures
+      };
+      continue;
+    }
+
+    /*
+     * The schema is validated here, and nowhere earlier.
+     *
+     * It was stored as written and served back opaquely, so this is the first
+     * place that knows what a schema is supposed to look like. A failure is
+     * NOT damage and not anyone's mistake - Val's schema format is allowed to
+     * move, and an older project opened in a newer Val (or the reverse) lands
+     * exactly here. The module reads as one this version cannot show, and the
+     * rest of the commit is unaffected.
+     */
+    const schemaRes = internal.SerializedSchema.safeParse(version.schema);
+    if (!schemaRes.success) {
+      failures.push({
+        kind: "schema-unreadable",
+        moduleFilePath,
+        message: zodValidationError.fromError(schemaRes.error).toString()
+      });
+      modules[moduleFilePath] = {
+        source: version.source,
+        schema: null,
+        patchIds,
+        changedPaths,
+        failures
+      };
+      continue;
+    }
+    modules[moduleFilePath] = {
+      source: version.source,
+      schema: schemaRes.data,
+      patchIds,
+      changedPaths,
+      failures
+    };
+  }
+  const entriesRes = await resolveJsonEntriesAtCommit(ops, commitSha, affectedFiles);
+  let jsonEntries = {};
+  if (fp.result.isErr(entriesRes)) {
+    // Entry contents are supporting detail, not the commit. Losing them should
+    // narrow what can be shown, not hide the commit entirely.
+    warnings.push(entriesRes.error);
+  } else {
+    jsonEntries = entriesRes.value.entries;
+    warnings.push(...entriesRes.value.failures);
+  }
+  return fp.result.ok({
+    commit,
+    modules,
+    patches,
+    jsonEntries,
+    binaryFiles: describeBinaryFilesAtCommit(commitSha, affectedFiles, (options === null || options === void 0 ? void 0 : options.apiBasePath) ?? "/api/val"),
+    warnings
+  });
+}
+
+/**
+ * One module, as of a commit — including a commit that never touched it.
+ *
+ * `getHistoricalPatchSet` answers "what did this commit change", which is what
+ * a commit IS. This answers "how did this module look at that point", which is
+ * what someone comparing two panes is asking as soon as they navigate off the
+ * changed set — and without it the history pane can only show a handful of
+ * modules per commit.
+ *
+ * `null` means history has no record at or before that commit: the module was
+ * last edited before recording started, or never. That is deliberately NOT the
+ * same as a module the commit deleted, which is a recorded fact with a source
+ * of `null`, and not the same as an error.
+ */
+async function getModuleAtCommit(ops, commitSha, moduleFilePath) {
+  const res = await ops.getCommitModules(commitSha, {
+    asOf: true,
+    moduleFilePath
+  });
+  if (fp.result.isErr(res)) {
+    return res;
+  }
+  const version = res.value.modules.find(module => module.moduleFilePath === moduleFilePath);
+  if (version === undefined) {
+    return fp.result.ok(null);
+  }
+  if (version.unavailable) {
+    return fp.result.ok({
+      source: null,
+      schema: null,
+      patchIds: [],
+      changedPaths: [],
+      failures: [{
+        kind: "source-unavailable",
+        moduleFilePath
+      }]
+    });
+  }
+  // Validated here, not at the transport boundary, for the same reason as in
+  // `getHistoricalPatchSet`: a schema this Val cannot read is one module it
+  // cannot show, not a failed request.
+  const schemaRes = internal.SerializedSchema.safeParse(version.schema);
+  if (!schemaRes.success) {
+    return fp.result.ok({
+      source: version.source,
+      schema: null,
+      patchIds: [],
+      changedPaths: [],
+      failures: [{
+        kind: "schema-unreadable",
+        moduleFilePath,
+        message: zodValidationError.fromError(schemaRes.error).toString()
+      }]
+    });
+  }
+  return fp.result.ok({
+    source: version.source,
+    schema: schemaRes.data,
+    // Empty, and correct: this module may well have been changed by an EARLIER
+    // commit than the one asked about, and those are that commit's patches.
+    patchIds: [],
+    changedPaths: [],
+    failures: []
+  });
+}
+
+const host = process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
+const SettingsSchema = z.z.object({
+  publicProjectId: z.z.string(),
+  remoteFileBuckets: z.z.array(z.z.object({
+    bucket: z.z.string()
+  }))
+});
+async function getSettings(projectName, auth) {
+  try {
+    const response = await fetch(`${host}/v1/${projectName}/settings`, {
+      headers: "pat" in auth ? {
+        "x-val-pat": auth.pat,
+        "Content-Type": "application/json"
+      } : {
+        Authorization: `Bearer ${auth.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (response.status === 404) {
+      return {
+        success: false,
+        message: `Project '${projectName}' not found: verify that the name of the project is correct and that you have access to it.`
+      };
+    }
+    if (response.status !== 200) {
+      return {
+        success: false,
+        message: `Failed to get project id: ${response.statusText}`
+      };
+    }
+    const json = await response.json();
+    const parseRes = SettingsSchema.safeParse(json);
+    if (!parseRes.success) {
+      return {
+        success: false,
+        message: `Failed to parse settings data: ${parseRes.error.message}`
+      };
+    }
+    return {
+      success: true,
+      data: parseRes.data
+    };
+  } catch {
+    return {
+      success: false,
+      message: `Failed to get project id. Check network connection and try again.`
+    };
+  }
+}
+
+/**
+ * Resolving how Val is configured, and building the data layer from it.
+ *
+ * Both live here rather than inside `createValApiRouter` because the MCP tool
+ * registry needs exactly the same answers: which mode we are in, which
+ * credential to use, and which `ValOps` implementation that implies. Two copies
+ * of this would drift, and the failure would be quiet — a registry that decides
+ * it is in fs mode while the Studio decides it is in proxy mode reads different
+ * content from the same project.
+ *
+ * The type-only import from `./ValRouter` is deliberate: it keeps `ValApiOptions`
+ * where its documentation lives without creating a runtime cycle.
+ *
+ * The credential-bearing URL check at the bottom of this file lives here for the
+ * same reason: it is a check on the URLs `initHandlerOptions` resolves, and its
+ * only caller is that function. Leaving it in `./ValRouter` would have meant
+ * importing it back from there, which is the runtime cycle the paragraph above
+ * exists to avoid.
+ */
+
+const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
+
 /**
  * Resolve options plus environment into a concrete {@link ValServerConfig}.
  *
@@ -8102,31 +9135,39 @@ async function initHandlerOptions(route, opts, config) {
 /**
  * Build the data layer a {@link ValServerConfig} calls for.
  *
- * `auth` decides *whose* credential the http backend sees. Left out, it is the
- * app's own API key — which is what the Studio wants, because there the app has
- * already verified a session cookie and is acting on the user's behalf under its
- * own authority.
+ * The http backend always sees the app's own API key. That is what the Studio
+ * wants — there the app has already verified a session cookie and is acting on
+ * the user's behalf under its own authority — and it is now the only shape:
+ * every caller that reaches here has been authenticated by the app itself, so
+ * there is no request left on which the app is a pipe rather than an authority.
  *
- * A caller acting for a user it has *not* authenticated itself must pass that
- * user's personal access token instead, so the backend is the one that decides
- * what the caller may do. That is the whole of `docs/plans/mcp.md` D.2: the app
- * stops being an authority and goes back to being a pipe. Passing the app's API
- * key on such a request is the D.6 confused deputy, and it is worth being blunt
- * about why it is tempting — it works, and it works for every project the key
- * can reach, including the ones the caller cannot.
+ * This took a parameter for the other case: a caller acting for a user it had
+ * *not* authenticated passed that user's personal access token, and the backend
+ * decided what the caller could do. `ValOpsHttp` still accepts such a token —
+ * the CLI's `debug` command uses the developer's own from `val login` — but no
+ * server request builds one any more, because a request the app cannot
+ * authenticate is now refused instead of relayed.
+ *
+ * What has not changed is why the API key must never stand in for a credential
+ * that was merely *absent*: it works, and it works for every project the key
+ * can reach, including the ones the caller cannot. Callers are refused for a
+ * missing credential well before this point.
  */
-function createValOps(valModules, options, auth) {
+function createValOps(valModules, options) {
   if (options.mode === "fs") {
     // No credential in fs mode: this reads and writes the developer's own
-    // working tree, and there is no backend to authenticate to. A PAT handed in
-    // here is not ignored quietly — the caller is told, in createValTools.
+    // working tree, and there is no backend to authenticate to. A credential
+    // that arrives for such a project is not ignored quietly — the caller is
+    // told, by `createValTools` when the project is configured for oauth and by
+    // `initValMcp` when it is not, since with no issuer there is no verified
+    // credential left for the registry to see.
     return new ValOpsFS(options.valContentUrl, options.cwd, valModules, {
       formatter: options.formatter,
       config: options.config
     });
   }
   if (options.mode === "http") {
-    return new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, auth ?? {
+    return new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, {
       apiKey: options.apiKey
     }, valModules, {
       formatter: options.formatter,
@@ -8748,90 +9789,6 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
-    "/session": {
-      GET: async req => {
-        const cookies = req.cookies;
-        if (serverOps instanceof ValOpsFS) {
-          return {
-            status: 200,
-            json: {
-              mode: "local",
-              enabled: await callbacks.isEnabled()
-            }
-          };
-        }
-        if (!options.project) {
-          return {
-            status: 500,
-            json: {
-              message: "Project is not set"
-            }
-          };
-        }
-        if (!options.valSecret) {
-          return {
-            status: 500,
-            json: {
-              message: "Secret is not set"
-            }
-          };
-        }
-        return withAuth(options.valSecret, cookies, "session", async data => {
-          if (!options.valBuildUrl) {
-            return {
-              status: 500,
-              json: {
-                message: "Val is not correctly setup. Build url is missing"
-              }
-            };
-          }
-          const url = new URL(`/api/val/${options.project}/auth/session`, options.valBuildUrl);
-          const fetchRes = await fetch(url, {
-            headers: getAuthHeaders(data.token, "application/json")
-          });
-          if (fetchRes.status === 200) {
-            const json = z.z.object({
-              member_role: z.z.union([z.z.literal("owner"), z.z.literal("developer"), z.z.literal("editor")]).optional(),
-              id: z.z.string(),
-              full_name: z.z.string().optional(),
-              username: z.z.string().optional(),
-              avatar_url: z.z.string().optional()
-            }).safeParse(await fetchRes.json());
-            if (json.success) {
-              return {
-                status: fetchRes.status,
-                json: {
-                  mode: "proxy",
-                  enabled: await callbacks.isEnabled(),
-                  ...json.data
-                }
-              };
-            } else {
-              const message = internal.getErrorMessageFromUnknownJson(json, "Could not parse session response. Unexpected error (no error message). Status: " + fetchRes.status);
-              return {
-                status: 500,
-                json: {
-                  message: message,
-                  ...json
-                }
-              };
-            }
-          } else {
-            const json = z.z.object({
-              message: z.z.string()
-            }).safeParse(await fetchRes.json());
-            const message = internal.getErrorMessageFromUnknownJson(json, "Unknown error");
-            return {
-              status: fetchRes.status,
-              json: {
-                message: message,
-                ...json
-              }
-            };
-          }
-        });
-      }
-    },
     "/logout": {
       GET: async req => {
         const query = req.query;
@@ -11045,11 +12002,13 @@ const ValServer = (valModules, options, callbacks) => {
                     }
                   };
                 }
-                const arrayBuffer = await binaryRes.arrayBuffer();
-                const base64 = Buffer.from(arrayBuffer).toString("base64");
-                const dataUrl = `data:${file.metadata.mimeType};base64,${base64}`;
+                // Bytes straight through. This used to base64 the buffer,
+                // wrap it in a data: URL, and hand that to a method whose first
+                // act was to unwrap it again - ceremony to satisfy a convention
+                // that no longer exists.
+                const bytes = Buffer.from(await binaryRes.arrayBuffer());
                 const type = file.metadata.mimeType.startsWith("image/") ? "image" : "file";
-                const saveRes = await serverOps.saveBase64EncodedBinaryFileFromPatch(file.filePath, req.body.parentRef, req.body.patchId, dataUrl, type, file.metadata);
+                const saveRes = await serverOps.saveBinaryFileFromPatch(file.filePath, req.body.parentRef, req.body.patchId, bytes, file.metadata.mimeType, type, file.metadata);
                 if (saveRes.error) {
                   return {
                     status: 500,
@@ -11177,6 +12136,137 @@ const ValServer = (valModules, options, callbacks) => {
       }
     },
     //#region files
+    // #region history
+    "/history/commits": {
+      GET: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await serverOps.listCommits(req.query.branch, {
+          limit: req.query.limit,
+          cursor: req.query.cursor
+        });
+        if (fp.result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        return {
+          status: 200,
+          json: res.value,
+          // The head moves, so a listing is never reusable.
+          headers: {
+            "Cache-Control": "no-store"
+          }
+        };
+      }
+    },
+    "/history/commit": {
+      GET: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await getHistoricalPatchSet(serverOps, req.query.commit_sha);
+        if (fp.result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        /*
+         * Immutable ONLY when nothing in the answer was transient.
+         *
+         * What a commit recorded cannot change, so a clean answer is reusable
+         * forever - that is what makes comparing many commits cheap. But a
+         * module marked `unavailable` means a blob fetch failed, and a warning
+         * means an entry read against GitHub did; both can succeed on the next
+         * try. Cached for a year, one flaky read would become "nothing was
+         * recorded for this module" for the rest of the session and beyond.
+         *
+         * `private`, not `public`: this route is behind the session cookie, and
+         * a shared cache holding it would hand one project's module sources to
+         * whoever asked next. The browser's own cache is where the reuse was
+         * wanted anyway.
+         */
+        const settled = res.value.warnings.length === 0 && Object.values(res.value.modules).every(module => module.failures.length === 0);
+        return {
+          status: 200,
+          json: res.value,
+          headers: {
+            "Cache-Control": settled ? "private, max-age=31536000, immutable" : "no-store"
+          }
+        };
+      }
+    },
+    "/history/module": {
+      GET: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await getModuleAtCommit(serverOps, req.query.commit_sha, req.query.module_file_path);
+        if (fp.result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        // Immutable only when the answer settled — a module reported
+        // unavailable means a blob fetch failed and may succeed next time, and
+        // caching that for a year turns one flaky read into a permanent gap.
+        const settled = res.value === null || res.value.failures.length === 0;
+        return {
+          status: 200,
+          json: {
+            moduleFilePath: req.query.module_file_path,
+            module: res.value
+          },
+          headers: {
+            "Cache-Control": settled ? "private, max-age=31536000, immutable" : "no-store"
+          }
+        };
+      }
+    },
+    "/history/files": {
+      GET: async req => {
+        // No auth, for the same reason /files has none: this is served to an
+        // <img> that the app's own backend may fetch during image
+        // optimisation, with no cookies. What it exposes is a file at a commit
+        // that is already in the repository.
+        const res = await serverOps.getFileAtCommit(req.query.commit_sha, req.query.path, req.query.remote === "true");
+        if (fp.result.isErr(res)) {
+          const response = historyErrorResponse(res.error);
+          // The stream branch of this route's response union has no json, so
+          // narrow to the shapes it does allow.
+          if (response.status === 401 || response.status === 404) {
+            return response;
+          }
+          return {
+            status: 400,
+            json: response.json
+          };
+        }
+        return {
+          status: 200,
+          headers: {
+            "Content-Type": guessMimeTypeFromPath(req.query.path) ?? "application/octet-stream",
+            // A file at a fixed commit cannot change.
+            "Cache-Control": "public, max-age=31536000, immutable"
+          },
+          body: bufferToReadableStream(res.value)
+        };
+      }
+    },
+    // #endregion history
     "/files": {
       GET: async req => {
         const query = req.query;
@@ -11675,6 +12765,45 @@ const ENABLE_COOKIE_VALUE = {
   }
 };
 const chunkSize = 1024 * 1024;
+
+/**
+ * Turn a HistoryError into the HTTP answer it deserves.
+ *
+ * The `kind` travels in the body alongside the message, because the Studio
+ * decides what to OFFER from it - "cannot restore this field" and "cannot
+ * restore this module at all" are different affordances, and a rendered string
+ * cannot be told apart.
+ */
+function historyErrorResponse(error) {
+  const message = historyErrorMessage(error);
+  switch (error.kind) {
+    case "commit-not-found":
+      return {
+        status: 404,
+        json: {
+          message
+        }
+      };
+    case "not-supported-in-fs-mode":
+      // Not an error in the request - this deployment simply has no history
+      // service. 400 rather than 500 so it does not read as a bug.
+      return {
+        status: 400,
+        json: {
+          message,
+          kind: error.kind
+        }
+      };
+    default:
+      return {
+        status: 500,
+        json: {
+          message,
+          kind: error.kind
+        }
+      };
+  }
+}
 function bufferToReadableStream(buffer) {
   const stream = new ReadableStream({
     start(controller) {
@@ -12755,21 +13884,22 @@ async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
   }
 
   /**
-   * Null on the PAT path, and the verified profile on the token path.
+   * The verified profile, or null when there was nothing to verify.
    *
-   * The PAT case is unchanged and still deliberate: the app cannot resolve a
-   * PAT, so any id it wrote here would be an unverified claim dressed up as a
-   * checked one — and the request already carries the caller's own token, which
-   * is a better answer to "who did this" than anything the app could assert.
-   * Attributing that patch is the backend's job.
+   * An author is written only when somebody checked it. On the token path the
+   * host verified a signature over a key it does not hold, so the profile is
+   * checked rather than claimed, and the backend has no token of its own to
+   * attribute from — the call reaches it under the app's API key. If this
+   * stayed null there, every edit made through a signed-in editor's own session
+   * would land with no author at all, which is worse than useless on a CMS
+   * whose review screen is organised by who changed what.
    *
-   * The token case is the opposite situation, which is why it gets the opposite
-   * answer. The host verified a signature over a key it does not hold, so the
-   * profile is checked rather than claimed, and the backend has no token of its
-   * own to attribute from — the call reaches it under the app's API key. If this
-   * stayed null, every edit made through a signed-in editor's own session would
-   * land with no author at all, which is worse than useless on a CMS whose
-   * review screen is organised by who changed what.
+   * Null is what local filesystem mode gets, where there is no credential to
+   * resolve, exactly as the Studio does locally. It is also what the removed
+   * personal-access-token path got, and for a reason worth keeping in view: an
+   * id derived from a credential the app cannot resolve is an unverified claim
+   * dressed up as a checked one. Should another unverified credential ever
+   * reach here, null remains its only honest author.
    */
   const authorId = ((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) === "verified-profile" ? ctx.auth.profileId : null;
   for (let attempt = 0; attempt < 2; attempt++) {
@@ -13027,14 +14157,17 @@ function rejectFileOps(patch) {
  */
 
 /**
- * How the caller was established, and it is a union because there are two
- * genuinely different answers — with different consequences downstream.
+ * How the caller was established, and there is one acceptable answer: the host
+ * **checked a signature**.
  *
- * The distinction that matters is **who checked**. A PAT is forwarded to the
- * backend unchecked, because the app cannot resolve one; an access token is
- * verified by the app itself, against a public key it does not hold and
- * therefore cannot forge. The first is a credential being relayed. The second
- * is a signature that has already been checked.
+ * A union of one, deliberately. It carried a second variant — a personal access
+ * token relayed to the backend unchecked, on the reasoning that the app cannot
+ * resolve one and the backend can. The reasoning held; the shape did not. A
+ * credential the host cannot check is one it also cannot refuse, so accepting
+ * one made "a deployed endpoint that authenticates nobody" a supported
+ * configuration, and it let a host serve these tools without ever being told
+ * where callers should authorize. The discriminant stays so that adding a
+ * second *verified* kind stays a one-line change at every call site.
  */
 
 /**
@@ -13069,17 +14202,6 @@ const VAL_SCOPE_READ = "val:read";
 /** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
 const VAL_SCOPE_WRITE = "val:write";
 
-/**
- * How many callers' data layers to keep around in proxy mode.
- *
- * Each entry holds one `ValOpsHttp`, and each of those caches the project's
- * evaluated modules once `initSources` has run — so this bounds memory, not just
- * entry count. Small on purpose: the cost of a miss is re-evaluating the
- * modules on the next call, which is what happened on *every* call before this
- * cache existed.
- */
-const MAX_CACHED_OPS = 8;
-
 /**
  * Val's server-side tool registry.
  *
@@ -13179,17 +14301,25 @@ function createValTools(valModules, options) {
  * Pick the data layer for a call, which in proxy mode means picking whose
  * credential the backend will see.
  *
- * This is the one place authorization is decided, and it decides it by *not*
- * deciding: in proxy mode the caller's own personal access token goes to the
- * backend, which is the only party that can say what that token may do. The app
- * never inspects it, never caches a verdict about it, and never substitutes its
- * own API key for a missing one — see `docs/plans/mcp.md` D.2.
+ * This is the one place authorization is decided, and in proxy mode there is
+ * exactly one credential it will act on: an access token whose signature,
+ * issuer, audience and expiry the host verified against the authorization
+ * server's published key. Anything less is refused here rather than forwarded.
+ *
+ * There used to be a second route — the caller's personal access token, passed
+ * through unread on the reasoning that the backend, not the app, is the
+ * authority on what it may do. That was true, and it was still the wrong shape:
+ * it made an unauthenticated bearer token on a deployed endpoint a supported
+ * configuration, and it meant `initValMcp` had a path where an app served MCP
+ * without ever being told where to authorize. A host that has not verified
+ * anything now gets a refusal that names the missing `oauth` config.
  *
- * The alternative shape, and the reason this function exists at all, is an
- * `authenticate()` that checks the PAT once and then acts under the app's key.
- * That reads as more secure and is strictly less so: the check happens in the
- * app, so every bug in it becomes full access to every project the app's key
- * can reach, and the backend's own permission model stops being consulted (D.6).
+ * What has *not* changed is why a verified token does not become the app's own
+ * API key by some other name. The app authenticates to the backend with its own
+ * key here, and who did what travels as the patch's `authorId` — so the
+ * profile has to be one the host checked cryptographically, never one it was
+ * handed. An `authenticate()` that decided a credential's rights inside the app
+ * would make every bug in it full access to every project that key can reach.
  */
 function createOpsResolver(valModules, options) {
   if (options.mode === "fs") {
@@ -13203,18 +14333,17 @@ function createOpsResolver(valModules, options) {
         // and the difference matters, because fs mode writes straight to disk
         // with no backend permission check at all.
         //
-        // The two credentials get different messages because they arrive here
-        // for different reasons. A PAT is something the caller chose to send. A
-        // verified access token is not: it only exists because this app
-        // advertised an authorization server, so the developer seeing this did
-        // not do anything wrong — a config file did, and naming it is the
-        // difference between a two-minute fix and an afternoon.
+        // A verified access token is not something the caller chose to send: it
+        // only exists because this app advertised an authorization server, so
+        // the developer seeing this did not do anything wrong — a config file
+        // did, and naming it is the difference between a two-minute fix and an
+        // afternoon.
         return {
           status: "error",
           result: {
             status: "error",
             code: "unsupported",
-            message: ctx.auth.type === "verified-profile" ? "This Val project is running in local filesystem mode, so there is nothing to authenticate against, but it is configured with an `oauth` issuer and is therefore asking clients for an access token it cannot use. Remove the `oauth` config (or `VAL_OAUTH_ISSUER` from your local `.env`) for local development." : "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
+            message: "This Val project is running in local filesystem mode, so there is nothing to authenticate against, but it is configured with an `oauth` issuer and is therefore asking clients for an access token it cannot use. Remove the `oauth` config (or `VAL_OAUTH_ISSUER` from your local `.env`) for local development."
           }
         };
       }
@@ -13225,78 +14354,50 @@ function createOpsResolver(valModules, options) {
     };
   }
 
-  // Keyed by a hash of the PAT, so the same caller reuses their own instance and
-  // two callers can never share one. Hashing is not a security boundary — the
-  // instance holds the token regardless — but it keeps credentials out of the
-  // key set, which is the thing that ends up in a heap dump or an error dump.
-  const byPatHash = new Map();
   /**
-   * One instance for every verified caller, and unlike the PAT map that is
-   * correct rather than a shortcut: this instance authenticates with the app's
-   * own API key, so there is nothing per-caller in it to keep apart. Who did
-   * what travels as the patch's `authorId` instead — see `writePath`.
+   * One instance for every verified caller, and that is correct rather than a
+   * shortcut: this instance authenticates with the app's own API key, so there
+   * is nothing per-caller in it to keep apart. Who did what travels as the
+   * patch's `authorId` instead — see `writePath`.
+   *
+   * One instance is also all proxy mode keeps now. It could not share while a
+   * personal access token reached this function: each token needed its own
+   * `ValOpsHttp` to hold it, each of those cached the project's evaluated
+   * modules, and the bounded cache that kept that memory in check turned an
+   * eviction into a re-evaluation of every module on the next call.
    */
   let sharedOps = null;
   return ctx => {
-    if (!ctx.auth) {
+    var _ctx$auth;
+    if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
       return {
         status: "error",
         result: {
           status: "error",
           code: "forbidden",
-          message: "This Val project talks to the Val content backend, so every call needs a credential: an access token from the Val authorization server, or the caller's own personal access token from `val login`."
+          message: "This Val project talks to the Val content backend, so every call needs an access token from the Val authorization server. If this endpoint is not asking clients to authorize, it has no `oauth` config — give `initValMcp` one, or run the project in local filesystem mode for development."
         }
       };
     }
-    if (ctx.auth.type === "verified-profile") {
-      if (!options.apiKey) {
-        // Proxy mode is inferred from the api key being present, so this is
-        // unreachable through `initHandlerOptions`. It stays because the
-        // alternative to refusing is building ops with no credential at all.
-        return {
-          status: "error",
-          result: {
-            status: "error",
-            code: "forbidden",
-            message: "This Val project has no API key configured, so a verified access token cannot be exchanged for backend access."
-          }
-        };
-      }
-      if (!sharedOps) {
-        sharedOps = createValOps(valModules, options);
-      }
-      return {
-        status: "ok",
-        ops: sharedOps
-      };
-    }
-    const key = node_crypto.createHash("sha256").update(ctx.auth.pat).digest("hex");
-    const cached = byPatHash.get(key);
-    if (cached) {
-      // Re-inserted so eviction drops the least recently used rather than the
-      // oldest — a long-running caller should not be evicted by a burst of
-      // one-off ones.
-      byPatHash.delete(key);
-      byPatHash.set(key, cached);
+    if (!options.apiKey) {
+      // Proxy mode is inferred from the api key being present, so this is
+      // unreachable through `initHandlerOptions`. It stays because the
+      // alternative to refusing is building ops with no credential at all.
       return {
-        status: "ok",
-        ops: cached
+        status: "error",
+        result: {
+          status: "error",
+          code: "forbidden",
+          message: "This Val project has no API key configured, so a verified access token cannot be exchanged for backend access."
+        }
       };
     }
-    const ops = createValOps(valModules, options, {
-      pat: ctx.auth.pat
-    });
-    byPatHash.set(key, ops);
-    while (byPatHash.size > MAX_CACHED_OPS) {
-      const oldest = byPatHash.keys().next();
-      if (oldest.done) {
-        break;
-      }
-      byPatHash.delete(oldest.value);
+    if (!sharedOps) {
+      sharedOps = createValOps(valModules, options);
     }
     return {
       status: "ok",
-      ops
+      ops: sharedOps
     };
   };
 }
@@ -13394,14 +14495,18 @@ function describeZodError(error) {
  * the safe direction: a tool that forgets the hint is treated as a write and
  * demands the wider scope, rather than a write slipping through as a read.
  *
- * Only the verified-token path is checked. A PAT carries no scopes here by
- * design — the backend resolves it and decides — so there is nothing to
- * enforce, and inventing a default would be this app claiming an authority it
- * does not have.
+ * The early return is a call carrying no verified credential, and there is no
+ * scope to check because nothing granted one. In Val's own host that means
+ * local filesystem mode, where a project writing a developer's own working tree
+ * has no wider authority to withhold. A host assembling its own context can
+ * also reach it with an unauthenticated proxy-mode call — refused a few lines
+ * later, by `resolveOps`, for the credential rather than the scope. Every other
+ * caller arrives as a verified profile, carrying the scopes its token was
+ * issued with.
  */
 function refuseInsufficientScope(tool, ctx) {
-  var _ctx$auth, _tool$annotations;
-  if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
+  var _ctx$auth2, _tool$annotations;
+  if (((_ctx$auth2 = ctx.auth) === null || _ctx$auth2 === void 0 ? void 0 : _ctx$auth2.type) !== "verified-profile") {
     return null;
   }
   // Read is needed by every call, including the writes: a tool that changes
@@ -14930,6 +16035,25 @@ async function handleJsonValuesExtractEntry(ctx) {
   };
 }
 
+/**
+ * `external:upload` under `val validate --fix`: refuse, and say what to run.
+ *
+ * Every other fix in this registry rewrites something inside the repository —
+ * reversible, visible in a diff, wrong by at most one commit. This one would
+ * write entries into a live external store: not in a diff, not undone by
+ * `git revert`, and against production indistinguishable from an editor's
+ * publish. So a blanket `--fix` must never apply it.
+ *
+ * `fixableErrorMessage` rather than a plain error, because the error IS fixable
+ * — just not by this command.
+ */
+async function handleExternalUpload() {
+  return {
+    success: true,
+    fixableErrorMessage: "This entry is written inline but its record is .external(). " + "Run 'val external upload' to move it into the store — " + "'val validate --fix' will not write to a live store."
+  };
+}
+
 // Fix handler registry. `keyof:check-keys` and `router:check-route` are
 // resolved upfront by the shared resolveSchemaSourceFixes — they never reach
 // this registry, so they're excluded from the key set.
@@ -14952,7 +16076,8 @@ const currentFixHandlers = {
   "files:check-unique-folder": handleUniqueFolderCheck,
   "images:check-all-files": handleCheckAllFiles,
   "files:check-all-files": handleCheckAllFiles,
-  "jsonValues:extract-entry": handleJsonValuesExtractEntry
+  "jsonValues:extract-entry": handleJsonValuesExtractEntry,
+  "external:upload": handleExternalUpload
 };
 const deprecatedFixHandlers = {
   "image:replace-metadata": handleFileMetadata
@@ -15608,6 +16733,7 @@ Object.defineProperty(exports, 'hasRemoteFileSchema', {
 exports.DEFAULT_LOGIN_EXPIRES_IN_SECONDS = DEFAULT_LOGIN_EXPIRES_IN_SECONDS;
 exports.DEFAULT_LOGIN_HOST = DEFAULT_LOGIN_HOST;
 exports.DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = DEFAULT_LOGIN_POLL_INTERVAL_SECONDS;
+exports.EXTERNAL_RESULT = EXTERNAL_RESULT;
 exports.Service = Service;
 exports.VAL_SCOPE_READ = VAL_SCOPE_READ;
 exports.VAL_SCOPE_WRITE = VAL_SCOPE_WRITE;
@@ -15635,9 +16761,11 @@ exports.createValServer = createValServer;
 exports.createValTools = createValTools;
 exports.currentFixHandlers = currentFixHandlers;
 exports.decodeJwtWithoutVerifying = decodeJwtWithoutVerifying;
+exports.defineExternal = defineExternal;
 exports.describePatchStoreProblems = describePatchStoreProblems;
 exports.downloadFileFromRemote = downloadFileFromRemote;
 exports.encodeJwt = encodeJwt;
+exports.err = err$1;
 exports.evalValConfigFile = evalValConfigFile;
 exports.extractFileMetadata = extractFileMetadata;
 exports.extractImageMetadata = extractImageMetadata;
@@ -15657,6 +16785,7 @@ exports.getPersonalAccessTokenPath = getPersonalAccessTokenPath;
 exports.getSettings = getSettings;
 exports.getValidationErrorFileRef = getValidationErrorFileRef;
 exports.handleCheckAllFiles = handleCheckAllFiles;
+exports.handleExternalUpload = handleExternalUpload;
 exports.handleFileMetadata = handleFileMetadata;
 exports.handleJsonValuesExtractEntry = handleJsonValuesExtractEntry;
 exports.handleRemoteFileCheck = handleRemoteFileCheck;
@@ -15665,7 +16794,9 @@ exports.handleRemoteFileUpload = handleRemoteFileUpload;
 exports.handleRemoteGalleryFileUpload = handleRemoteGalleryFileUpload;
 exports.handleUniqueFolderCheck = handleUniqueFolderCheck;
 exports.initHandlerOptions = initHandlerOptions;
+exports.isExternalResult = isExternalResult;
 exports.loadValModules = loadValModules;
+exports.ok = ok$1;
 exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;
 exports.patchSourceFile = patchSourceFile;
 exports.persistPersonalAccessToken = persistPersonalAccessToken;