@valbuild/server 0.120.4 → 0.122.0

package/dist/valbuild-server.esm.js

@@ -8,14 +8,14 @@ import path__default from 'path';
 import fs, { promises } from 'fs';
 import vm from 'node:vm';
 import { Module, createRequire } from 'node:module';
-import { resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api, filterBlockingValidationErrors, describeContainerAtPath, safeParsePatch, buildDuplicatePatch, buildEmptyAtPathPatch, buildRemoveImageGalleryEntryPatch } from '@valbuild/shared/internal';
+import { resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, JSONValue, PatchGroup, newestCommitSha, SerializedSchema, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api, filterBlockingValidationErrors, describeContainerAtPath, safeParsePatch, buildDuplicatePatch, buildEmptyAtPathPatch, buildRemoveImageGalleryEntryPatch } from '@valbuild/shared/internal';
 import { createUIRequestHandler } from '@valbuild/ui/server';
 import crypto$1 from 'crypto';
 import z$1, { z } from 'zod';
 import sizeOf from 'image-size';
 import { fromError } from 'zod-validation-error';
 import os from 'os';
-import { randomUUID, createHash } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { transform } from 'sucrase';
 import http from 'http';
 import https from 'https';
@@ -565,11 +565,13 @@ const patchValFile = async (id, rootDir, patch, 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);
@@ -1665,6 +1667,21 @@ class Service {
   getModuleFilePaths() {
     return Object.keys(this.extracted.sources);
   }
+
+  /**
+   * Everything that is wrong with how the project's modules are DECLARED, as
+   * opposed to what is in them.
+   *
+   * A module that failed to load is here, and so is a rule that spans the whole
+   * set — "one settings module, at the root" cannot be checked while looking at
+   * a single module, so `extractValModules` appends it with the offending path.
+   * `get` only surfaces these when the module is missing entirely, which a
+   * misplaced settings module is not: `val validate` reads them from here and
+   * reports them against the file.
+   */
+  getModuleErrors() {
+    return this.extracted.moduleErrors;
+  }
   serializedSchemaOf(moduleFilePath) {
     return this.extracted.serializedSchemas[moduleFilePath];
   }
@@ -1903,6 +1920,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.object({
   sub: z.string(),
   exp: z.number(),
@@ -2362,7 +2556,8 @@ class ValOps {
    * in-flight client patches the server has not seen) must pass
    * `applyPatches: false` or the same edits would be applied twice.
    */
-  async getJsonEntry(moduleFilePath, entryKey, opts) {
+  async getJsonEntry(moduleFilePath, entryKey, /** Passed straight through — see {@link getJsonEntries}. */
+  opts) {
     const res = await this.getJsonEntries(moduleFilePath, {
       keys: [entryKey]
     }, opts);
@@ -2456,7 +2651,7 @@ class ValOps {
           message: `Could not fetch patches: ${JSON.stringify(patchOps.errors)}`
         };
       }
-      modulePatches = patchOps.patches.filter(p => p.path === moduleFilePath && !p.appliedAt).map(p => ({
+      modulePatches = scopedModulePatches(patchOps.patches, moduleFilePath, opts === null || opts === void 0 ? void 0 : opts.patchIds).map(p => ({
         patchId: p.patchId,
         patch: p.patch
       }));
@@ -3686,6 +3881,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,
@@ -3698,7 +3934,8 @@ class ValOps {
       patchedBinaryFilesDescriptors,
       appliedPatches,
       skippedPatches,
-      triedPatches
+      triedPatches,
+      moduleVersions
     };
     return res;
   }
@@ -3716,8 +3953,21 @@ class ValOps {
   }
 
   // #region createPatch
-  async createPatch(path, patch, patchId, parentRef, sessionId, authorId) {
-    const saveRes = await this.saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId);
+  async createPatch(path, patch, patchId, parentRef, sessionId, authorId,
+  /**
+   * Which patch group this patch joins, recorded in the SAME request.
+   *
+   * Atomic on purpose. The content API runs every refusal before its insert,
+   * so an invalid closure is a 400 with nothing written. Recording membership
+   * in a second call would let a patch exist outside its author's group if
+   * that call failed — and a patch outside your own group is one you cannot
+   * publish until a repair puts it back.
+   *
+   * Optional: `fs` mode has no groups, and a client that predates them sends
+   * nothing.
+   */
+  patchGroup) {
+    const saveRes = await this.saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId, patchGroup);
     if (result.isErr(saveRes)) {
       console.error(`Could not save source patch at path: '${path}'. Error: ${saveRes.error.errorType === "other" ? saveRes.error.message : saveRes.error.errorType}`);
       if (saveRes.error.errorType === "patch-head-conflict") {
@@ -3732,11 +3982,76 @@ class ValOps {
     }
     return result.ok({
       patchId,
-      createdAt: new Date().toISOString()
+      createdAt: new Date().toISOString(),
+      // Spread rather than assigned: absent has to stay distinguishable from a
+      // group whose id is undefined, all the way to the client.
+      ...(saveRes.value.patchGroupId !== undefined ? {
+        patchGroupId: saveRes.value.patchGroupId
+      } : {})
     });
   }
 
   // #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;
@@ -3755,6 +4070,21 @@ function isOnlyFileCheckValidationError(validationError) {
 function isFileSource(value) {
   return typeof value === "object" && value !== null && "path" in value && typeof value.path === "string";
 }
+
+/**
+ * The patch group a newly created patch joins.
+ *
+ * `withPatchIds` is the CLOSURE the client computed — the patches that share
+ * a patch set with this one and must move with it. It is not derived here and
+ * must not be: the closure needs the content schema, and the service that
+ * stores groups does not have it. One implementation of that rule, on the side
+ * that can actually compute it.
+ *
+ * Membership rows are stamped with `coreVersion` on the content side, the same
+ * stamp the patch row itself carries, so which client wrote a row stays legible
+ * after the fact.
+ */
+
 function formatPatchSourceError(error) {
   if ("message" in error) {
     return error.message;
@@ -3765,6 +4095,33 @@ function formatPatchSourceError(error) {
     return "Unknown patch source error: " + JSON.stringify(_exhaustiveCheck);
   }
 }
+/**
+ * The patches a json entry render should apply, out of the whole chain.
+ *
+ * Three rules, and the second is the one that was missing. A draft page renders
+ * `jsonValues` entries beside module content, and only the modules were scoped
+ * — so one screen showed the caller's own view for its modules and base plus
+ * EVERY pending patch on the branch for the entries beside them, including
+ * another author's half-finished edit rendered as though it were live.
+ *
+ * 1. this module's, since the chain is branch-wide;
+ * 2. this caller's, when they asked to be scoped. `undefined` is "everything",
+ *    which is what every unscoped caller gets and must keep getting;
+ * 3. not already applied — a fact about this path rather than about scoping,
+ *    and true with or without a scope.
+ *
+ * Filtered here rather than by asking `fetchPatches` for a list, and that is
+ * load-bearing: both implementations read an empty `patchIds` as "no filter"
+ * and return the whole chain. That is the right default for a caller that
+ * cannot mean "none", and the most dangerous possible reading of a group that
+ * is genuinely empty — it would render every unpublished patch on the branch
+ * instead of base. It costs no round trip either: the whole chain is what the
+ * unscoped path fetches anyway.
+ */
+function scopedModulePatches(patches, moduleFilePath, patchIds) {
+  const scope = patchIds && new Set(patchIds);
+  return patches.filter(patch => patch.path === moduleFilePath && !patch.appliedAt && (scope === undefined || scope.has(patch.patchId)));
+}
 function getFieldsForType(type) {
   if (type === "file") {
     return ["mimeType"];
@@ -5795,7 +6152,17 @@ class ValOpsFS extends ValOps {
       };
     }
   }
-  async saveSourceFilePatch(path, patch, patchId, _parentRef, authorId, sessionId) {
+  async saveSourceFilePatch(path, patch, patchId, _parentRef, authorId, sessionId,
+  /*
+   * Named and ignored, rather than omitted from the signature.
+   *
+   * `fs` mode has no shared store and exactly one author, so there is nothing
+   * for a group to separate — every pending patch is already this person's.
+   * Declaring it makes that a decision a reader can see: TypeScript lets an
+   * implementation take fewer parameters than the abstract, so leaving it off
+   * would drop group membership silently and look identical to handling it.
+   */
+  _patchGroup) {
     const patchesDir = this.getPatchesDir();
     const record = {
       patch,
@@ -6290,6 +6657,46 @@ class ValOpsFS extends ValOps {
   getPatchLockFile() {
     return path__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 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"
+    });
+  }
+  // #endregion history
 }
 class FSOpsHost {
   constructor() {}
@@ -6552,7 +6959,14 @@ const FilesResponse = z.object({
   })])).optional()
 });
 const SavePatchResponse = z.object({
-  patchId: PatchId
+  patchId: PatchId,
+  /**
+   * Which group the content API put this patch in.
+   *
+   * Optional: a content API that predates patch groups does not send one, and
+   * absence has to keep meaning "no groups here" rather than failing the save.
+   */
+  patchGroupId: z.string().optional()
 });
 const DeletePatchesResponse = z.object({
   deleted: z.array(PatchId),
@@ -6570,10 +6984,126 @@ const CommitResponse = z.object({
   commit: CommitSha,
   branch: 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.object({
+  commitSha: z.string(),
+  parentCommitSha: z.string(),
+  clientCommitSha: z.string(),
+  branch: z.string(),
+  createdBranch: z.string().nullable(),
+  creator: z.string().nullable(),
+  message: z.string().nullable(),
+  createdAt: z.string(),
+  seqNum: z.string(),
+  patchCount: z.number(),
+  hasArchive: z.boolean()
+});
+const ListCommitsResponse = z.object({
+  commits: z.array(HistoricalCommitResponse),
+  nextCursor: z.string().nullable()
+});
+const CommitPatchesResponse = z.object({
+  commitSha: z.string(),
+  commit: z.object({
+    commitSha: z.string(),
+    parentCommitSha: z.string(),
+    clientCommitSha: z.string(),
+    branch: z.string(),
+    createdBranch: z.string().nullable(),
+    creator: z.string().nullable(),
+    message: z.string().nullable(),
+    createdAt: z.string(),
+    seqNum: z.string(),
+    hasArchive: z.boolean()
+  }),
+  patches: z.array(z.object({
+    patchId: z.string(),
+    path: z.string(),
+    patch: z.unknown(),
+    authorId: z.string().nullable(),
+    createdAt: z.string(),
+    baseSha: z.string(),
+    coreVersion: 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.object({
+  commitSha: z.string(),
+  parentCommitSha: 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.boolean().optional(),
+  modules: z.array(z.object({
+    moduleFilePath: z.string(),
+    commitSha: z.string(),
+    sourceSha: z.string().nullable(),
+    schemaSha: z.string(),
+    // Validated, because a Source IS just JSON and this side knows that much.
+    source: JSONValue.nullable(),
+    schema: z.unknown(),
+    unavailable: z.boolean()
+  }))
+});
+const CommitAffectedFilesResponse = z.object({
+  commitSha: z.string(),
+  files: z.array(z.union([z.object({
+    kind: z.union([z.literal("module-source"), z.literal("json-entry"), z.literal("binary")]),
+    gitPath: z.string(),
+    change: z.union([z.literal("added"), z.literal("modified"), z.literal("deleted")])
+  }), z.object({
+    kind: z.literal("remote-binary"),
+    ref: z.string(),
+    change: z.union([z.literal("added"), z.literal("modified"), z.literal("deleted")])
+  })]))
+});
+// #endregion history wire schemas
+
+/*
+ * The shared schema, not a copy of it.
+ *
+ * This re-declared `PatchGroup` field for field while the file already imported
+ * `PatchGroupT` from the same module — so a field added on one side and not the
+ * other would have `getPatchGroups()` return a `PatchGroupT[]` silently missing
+ * it, with no type error anywhere.
+ */
+const PatchGroupsResponse = z.object({
+  patchGroups: z.array(PatchGroup)
+});
+const PatchGroupMutationResponse = z.object({
+  patchGroupId: z.string(),
+  patchIds: z.array(PatchId)
+});
 const NonceResponse = z.object({
   nonce: z.string(),
   url: z.string()
 });
+
+/**
+ * How long a patch-group lookup is reused. See `ValOpsHttp.patchGroupsCache`.
+ *
+ * Sized to cover one server render, not to be a cache: several `fetchVal` calls
+ * in one request share an answer, and the next request asks again.
+ */
+const PATCH_GROUPS_CACHE_MS = 1000;
 class ValOpsHttp extends ValOps {
   constructor(contentUrl, project, commitSha,
   // TODO: CommitSha
@@ -6733,8 +7263,26 @@ class ValOpsHttp extends ValOps {
       }
     }
     const patches = [];
+    /*
+     * Which of them have SHIPPED, alongside which of them exist.
+     *
+     * A published patch stays in the chain with `appliedAt` set until the next
+     * deployment moves the base, so "in the chain" and "has shipped" are
+     * different questions — and the chain ids alone answer only the first. A
+     * client that already holds a record never re-fetches it, so it never
+     * learns the second: another author's publish left that patch in your scope
+     * as pending, your prefix gate read a hole in front of it, and Publish
+     * refused for a reason that had stopped being true.
+     *
+     * Sent as ids rather than folded into `patches`, so a client that ignores
+     * it behaves exactly as before.
+     */
+    const appliedPatches = [];
     for (const patchData of allPatchData.patches) {
       patches.push(patchData.patchId);
+      if (patchData.appliedAt) {
+        appliedPatches.push(patchData.patchId);
+      }
     }
     const webSocketNonceRes = await this.getWebSocketNonce(params.profileId);
     if (webSocketNonceRes.status === "error") {
@@ -6757,6 +7305,16 @@ class ValOpsHttp extends ValOps {
       commits: allPatchData.commits || [],
       deployments: allPatchData.deployments || [],
       patches,
+      appliedPatches,
+      /*
+       * The PUBLISH head, which is not `commitSha`.
+       *
+       * `commitSha` is the commit this deployment is serving and does not move
+       * when somebody publishes — only when the new build lands. This does, so
+       * it is what a client carries back to `/save` to say which world it
+       * decided against.
+       */
+      headCommitSha: newestCommitSha(allPatchData.commits) ?? undefined,
       commitSha: this.commitSha
     };
   }
@@ -6837,6 +7395,26 @@ class ValOpsHttp extends ValOps {
     }
     const allPatches = [];
     const allErrors = [];
+    /*
+     * The commits, which are a fact about the whole BRANCH, not about a chunk.
+     *
+     * This loop used to return only `patches` and `errors`, so a filtered fetch
+     * silently answered with no commits at all. That is not cosmetic:
+     * the publish-head guard in `ValServer` reads `newestCommitSha(commits)`,
+     * got `undefined` for every publish (a publish always names patch ids, so
+     * it always takes this branch), and skipped the check entirely. Two clients
+     * could publish against the same head with neither told.
+     *
+     * Taken from the first chunk that carries them, which is sound for the
+     * reason the dedupe below exists: each chunk's response describes the whole
+     * chain regardless of which ids it asked about.
+     *
+     * `deployments` is not carried, because it is declared only on
+     * `OrderedPatchesMetadata` and this is generic over both shapes. Nothing
+     * reads it from a filtered fetch today; if something starts to, it needs
+     * the same treatment and a home on `OrderedPatches` first.
+     */
+    let commits;
     if (patchIds === undefined || patchIds.length === 0) {
       return this.fetchPatchesInternal({
         patchIds: patchIds,
@@ -6854,6 +7432,9 @@ class ValOpsHttp extends ValOps {
       if (res.errors) {
         allErrors.push(...res.errors);
       }
+      if (commits === undefined && res.commits !== undefined) {
+        commits = res.commits;
+      }
     }
     // Chunking is a query-string-length workaround, NOT a filter: the content
     // api returns every applicable patch per request regardless of which
@@ -6880,7 +7461,13 @@ class ValOpsHttp extends ValOps {
     });
     return {
       patches,
-      errors: Object.keys(allErrors).length > 0 ? allErrors : undefined
+      errors: Object.keys(allErrors).length > 0 ? allErrors : undefined,
+      // Spread rather than set to `undefined`, so a caller that distinguishes
+      // "absent" from "empty" — `newestCommitSha` does not, but the annotation
+      // readers do — sees the same shape the unchunked path gives it.
+      ...(commits !== undefined ? {
+        commits
+      } : {})
     };
   }
   async fetchPatchesInternal(filters) {
@@ -6988,59 +7575,364 @@ class ValOpsHttp extends ValOps {
       };
     }
   }
-  async saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId) {
-    const baseSha = await this.getBaseSha();
-    return fetch(`${this.contentUrl}/v1/${this.project}/patches`, {
-      method: "POST",
-      headers: {
-        ...this.authHeaders,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        path,
-        patch,
-        authorId,
-        sessionId,
-        patchId,
-        parentPatchId: parentRef.type === "patch" ? parentRef.patchId : null,
-        baseSha,
-        commit: this.commitSha,
-        branch: this.branch,
-        coreVersion: Internal.VERSION.core
-      })
-    }).then(async res => {
-      var _res$headers$get2;
-      if (res.ok) {
-        const parsed = SavePatchResponse.safeParse(await res.json());
-        if (parsed.success) {
-          return result.ok({
-            patchId: parsed.data.patchId
-          });
-        }
-        return result.err({
-          errorType: "other",
-          message: `Could not parse save patch response. Error: ${fromError(parsed.error)}`
-        });
-      }
-      if (res.status === 409) {
-        return result.err({
-          errorType: "patch-head-conflict",
-          message: "Conflict: " + (await res.text())
-        });
-      }
-      if ((_res$headers$get2 = res.headers.get("Content-Type")) !== null && _res$headers$get2 !== void 0 && _res$headers$get2.includes("application/json")) {
-        const json = await res.json();
-        const message = getErrorMessageFromUnknownJson(json, "Unknown error");
-        return result.err({
-          errorType: "other",
-          message
-        });
-      }
-      return result.err({
-        errorType: "other",
-        message: "Could not save patch. HTTP error: " + res.status + " " + res.statusText
-      });
-    }).catch(e => {
+
+  // #region patch groups
+  /**
+   * Add patches to a patch group.
+   *
+   * The set arrives closed by the client — `withPatchIds` is the prefix closure
+   * over the patch sets the staged patches belong to. We forward it and do not
+   * second-guess it: deriving the closure needs the content schema, which this
+   * process does have but content.val.build does not, and having two
+   * implementations of the rule would be worse than having one.
+   *
+   * Membership rows are stamped with `coreVersion` on the content side — the
+   * same stamp the patch row carries — so which client wrote a row stays
+   * legible after the fact.
+   */
+  async stagePatches(patchGroupId, /** What the user asked to stage. */
+  patchIds,
+  /**
+   * What has to come with it, because the staged patches are written on top
+   * of it.
+   *
+   * The content API stores each membership row as `explicit` or `dependency`
+   * and treats what it is not told about as a dependency. Folding the two
+   * halves into `patchIds` therefore files the patch somebody clicked as one
+   * the closure dragged in — the exact opposite of what happened, and the
+   * only record anywhere of what the author chose.
+   */
+  withPatchIds,
+  /**
+   * WHO is asking, so the content API can refuse a group that is not theirs.
+   *
+   * Every call from this class carries the app's API key, which says which
+   * PROJECT is calling and nothing about which editor. Without this the
+   * content API cannot tell one of a project's editors from another, so the
+   * only check on stage and unstage is the one in `ValServer` — and anything
+   * reaching the content API by another route (an API key, a PAT) has none at
+   * all.
+   *
+   * `null` where there is no session. The content API refuses rather than
+   * treating that as a match: a group written by an api key has a null author
+   * too, and `null === null` must not read as ownership.
+   */
+  authorId) {
+    return this.mutatePatchGroup("POST",
+    // Encoded: patchGroupId arrives in a request body, so an unencoded value
+    // like "../../commit" would reach a different endpoint carrying this
+    // project's auth headers.
+    `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+      patchIds,
+      withPatchIds,
+      coreVersion: Internal.VERSION.core
+    }, authorId);
+  }
+
+  /**
+   * Remove patches from a patch group.
+   *
+   * The set arrives closed FORWARDS by the client: unstaging a patch also
+   * unstages everything built on top of it within its patch sets, and that is
+   * what `withPatchIds` carries.
+   */
+  async unstagePatches(patchGroupId, /** What the user asked to unstage. */
+  patchIds, /** What has to go with it: everything built on top of it. */
+  withPatchIds, /** See {@link stagePatches} — the content API's half of the ownership check. */
+  authorId) {
+    return this.mutatePatchGroup("DELETE", `patch-groups/${encodeURIComponent(patchGroupId)}/patches`, {
+      patchIds,
+      withPatchIds
+    }, authorId);
+  }
+
+  /**
+   * Every patch group on this branch, with what each holds.
+   *
+   * Read rather than mutated, and used to answer "which pending patches is THIS
+   * person allowed to see". A draft render that skips this shows base + every
+   * pending patch on the branch, including work other people have not
+   * published — which is what independent publish exists to prevent.
+   *
+   * A failure is an empty list rather than a throw, and the caller decides what
+   * that means. For a draft render the honest fallback is "show nothing
+   * pending" rather than "show everything": being shown your own committed
+   * content when the group lookup is down is a worse experience than being
+   * shown somebody else's unpublished draft is a bug.
+   */
+  /**
+   * The last group lookup, and when it was made.
+   *
+   * A draft render calls `getPatchGroups` once per `fetchVal`, in series with
+   * the whole-chain fetch, and a page that calls `fetchVal` several times pays
+   * the round trip several times. Groups are per branch and change rarely, so a
+   * short window removes the multiplier without letting a stage go unseen for
+   * meaningfully longer than one render.
+   *
+   * Deliberately short. This is a read whose staleness decides whose draft
+   * content someone sees, so it is a per-request de-duplication rather than a
+   * cache: a second render a second later asks again.
+   */
+  patchGroupsCache = null;
+  async getPatchGroups(options) {
+    const now = Date.now();
+    if ((options === null || options === void 0 ? void 0 : options.fresh) !== true && this.patchGroupsCache !== null && now - this.patchGroupsCache.at < PATCH_GROUPS_CACHE_MS) {
+      return this.patchGroupsCache.res;
+    }
+    const res = await this.fetchPatchGroups();
+    /*
+     * ANSWERS are cached; failures are not.
+     *
+     * A transient failure held for a second is replayed to every caller in it,
+     * and the callers are not equivalent: `refuseUnlessOwn` turns it into a 500
+     * that refuses the stage, a scoped draft render falls back to base and
+     * drops every pending patch on the page, and `GET /patches` omits the
+     * annotation. One flaky request became a second of all three. The point of
+     * this cache is to collapse the several `fetchVal` calls in one render into
+     * one round trip, and an error is exactly the case worth retrying inside
+     * that window rather than the case worth remembering.
+     *
+     * `unsupported` is cached with `ok` deliberately: it is a real answer about
+     * the deployment — this content API predates patch groups — and it will not
+     * change between two renders.
+     */
+    if (res.status === "ok" || res.status === "unsupported") {
+      this.patchGroupsCache = {
+        at: now,
+        res
+      };
+    }
+    return res;
+  }
+  async fetchPatchGroups() {
+    try {
+      /*
+       * `branch` is REQUIRED by the endpoint, which answers 400 without it.
+       *
+       * Same two params every other read here sends (`fetchPatchesInternal`,
+       * `saveSourceFilePatch`): groups are per branch, so a request without one
+       * is not merely under-specified, it is rejected.
+       */
+      const params = new URLSearchParams([["branch", this.branch]]);
+      const res = await fetch(`${this.contentUrl}/v1/${this.project}/patch-groups?${params}`, {
+        headers: this.authHeaders
+      });
+      if (res.status === 404) {
+        /*
+         * The endpoint is not there, which is a content API that PREDATES patch
+         * groups — not a failure.
+         *
+         * The distinction decides what a draft render shows, and collapsing it
+         * into "error" is not a small mistake: a caller that reads an error as
+         * "could not ask" renders BASE, so every existing http deployment would
+         * silently drop all pending content from every draft preview. "There
+         * are no groups here" has to mean unscoped, which is exactly the
+         * behaviour those projects have today.
+         */
+        return {
+          status: "unsupported"
+        };
+      }
+      if (!res.ok) {
+        return {
+          status: "error",
+          message: res.status === 401 ? "Could not read patch groups: unauthorized. Verify that the val api keys are correct." : `Could not read patch groups. HTTP error: ${res.status} ${res.statusText}`
+        };
+      }
+      const parsed = PatchGroupsResponse.safeParse(await res.json());
+      if (!parsed.success) {
+        return {
+          status: "error",
+          message: `Could not parse patch groups response. Error: ${fromError(parsed.error)}`
+        };
+      }
+      return {
+        status: "ok",
+        patchGroups: parsed.data.patchGroups
+      };
+    } catch (err) {
+      return {
+        status: "error",
+        message: `Could not read patch groups. Error: ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+  }
+  async mutatePatchGroup(method, path, body,
+  /**
+   * WHO is asking. Sent as `x-val-profile-id`, which is what the content API
+   * reads to decide whether this group is the caller's.
+   *
+   * `this.authHeaders` is the app's API key, and that names the PROJECT, not
+   * the person — so without this the content API cannot resolve a profile
+   * and refuses every stage and unstage with
+   * "Cannot resolve the caller's profile". The group endpoints are the only
+   * ones here that need it, because they are the only ones whose answer
+   * depends on which of a project's editors is calling.
+   *
+   * Omitted when there is no session rather than sent empty: the content API
+   * treats an unidentified caller as a refusal, which is what we want, and an
+   * empty header would be a different and less obvious way to say it.
+   *
+   * A PAT already identifies a person, so `authHeaders` carries the identity
+   * on its own there and this adds nothing.
+   */
+  authorId) {
+    try {
+      const res = await fetch(`${this.contentUrl}/v1/${this.project}/${path}`, {
+        method,
+        headers: {
+          ...this.authHeaders,
+          ...(authorId !== null ? {
+            "x-val-profile-id": authorId
+          } : {}),
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (res.ok) {
+        const parsed = PatchGroupMutationResponse.safeParse(await res.json());
+        if (parsed.success) {
+          return {
+            patchIds: parsed.data.patchIds
+          };
+        }
+        return {
+          status: 500,
+          patchIds: [],
+          error: {
+            message: `Could not parse patch group response. Error: ${fromError(parsed.error)}`
+          }
+        };
+      }
+      // 403 (not your group) and 409 (already published) are meaningful to the
+      // client, so they are passed through rather than flattened to a 500.
+      if (res.status === 403 || res.status === 409) {
+        // `home` answers these with a JSON body, so `res.text()` put the literal
+        // `{"message":"..."}` in front of the user. Every other branch in this
+        // class unwraps it; this one now does too.
+        return {
+          status: res.status,
+          patchIds: [],
+          error: {
+            message: getErrorMessageFromUnknownJson(await res.json().catch(() => undefined), `Could not update patch group. HTTP error: ${res.status} ${res.statusText}`)
+          }
+        };
+      }
+      // A 401 here is the app's own credentials failing, not the user's, so it gets
+      // the same wording as every other call in this class rather than an opaque
+      // 500 that sends the user looking at their own session.
+      if (res.status === 401) {
+        return {
+          status: 500,
+          patchIds: [],
+          error: {
+            message: "Although your user is authorized, the application has authorization issues. Contact the developers on your team and ask them to verify the api keys."
+          }
+        };
+      }
+      return {
+        status: 500,
+        patchIds: [],
+        error: {
+          message: `Could not update patch group. HTTP error: ${res.status} ${res.statusText}`
+        }
+      };
+    } catch (err) {
+      return {
+        status: 500,
+        patchIds: [],
+        error: {
+          message: `Could not update patch group (connection error?): ${err instanceof Error ? err.message : JSON.stringify(err)}`
+        }
+      };
+    }
+  }
+  // #endregion
+
+  async saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId, patchGroup) {
+    const baseSha = await this.getBaseSha();
+    return fetch(`${this.contentUrl}/v1/${this.project}/patches`, {
+      method: "POST",
+      headers: {
+        ...this.authHeaders,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        path,
+        patch,
+        authorId,
+        sessionId,
+        patchId,
+        parentPatchId: parentRef.type === "patch" ? parentRef.patchId : null,
+        baseSha,
+        commit: this.commitSha,
+        branch: this.branch,
+        coreVersion: Internal.VERSION.core,
+        /*
+         * Group membership in the SAME request as the patch.
+         *
+         * The content API runs every refusal before its insert, so an invalid
+         * closure is a 400 with nothing written. Spread rather than sent as
+         * nulls: a client with no group omits the fields entirely, which is
+         * what an older content API expects to see.
+         */
+        ...(patchGroup ? {
+          // Only when the caller named one. Omitted, the content API
+          // resolves this author's open group and creates it if absent,
+          // which is what every write wants.
+          ...(patchGroup.patchGroupId !== undefined ? {
+            patchGroupId: patchGroup.patchGroupId
+          } : {}),
+          withPatchIds: patchGroup.withPatchIds
+        } : {})
+      })
+    }).then(async res => {
+      var _res$headers$get2;
+      if (res.ok) {
+        const parsed = SavePatchResponse.safeParse(await res.json());
+        if (parsed.success) {
+          return result.ok({
+            patchId: parsed.data.patchId,
+            /*
+             * Passed back to the client, which cannot learn it any other way.
+             *
+             * A write names no group — the content API resolves this author's
+             * open group and CREATES it if absent — so on a fresh branch the
+             * group comes into existence here and nowhere else. The chain
+             * annotation is only re-read when a fetch has missing ids to ask
+             * for, and a patch this client made is never missing, so without
+             * this the tab that bootstrapped the group would never learn its
+             * id and every stage would be a no-op.
+             */
+            ...(parsed.data.patchGroupId !== undefined ? {
+              patchGroupId: parsed.data.patchGroupId
+            } : {})
+          });
+        }
+        return result.err({
+          errorType: "other",
+          message: `Could not parse save patch response. Error: ${fromError(parsed.error)}`
+        });
+      }
+      if (res.status === 409) {
+        return result.err({
+          errorType: "patch-head-conflict",
+          message: "Conflict: " + (await res.text())
+        });
+      }
+      if ((_res$headers$get2 = res.headers.get("Content-Type")) !== null && _res$headers$get2 !== void 0 && _res$headers$get2.includes("application/json")) {
+        const json = await res.json();
+        const message = getErrorMessageFromUnknownJson(json, "Unknown error");
+        return result.err({
+          errorType: "other",
+          message
+        });
+      }
+      return result.err({
+        errorType: "other",
+        message: "Could not save patch. HTTP error: " + res.status + " " + res.statusText
+      });
+    }).catch(e => {
       return result.err({
         errorType: "other",
         message: `Could save source file patch (connection error?): ${e instanceof Error ? e.message : e.toString()}`
@@ -7204,7 +8096,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();
@@ -7264,7 +8161,17 @@ class ValOpsHttp extends ValOps {
       }]
     };
   }
-  async deletePatches(patchIds) {
+  async deletePatches(patchIds,
+  /**
+   * Patches that are NOT deleted but must lose their group membership.
+   *
+   * Deleting a patch out of the middle of a patch set leaves every group
+   * still holding the rest with a non-prefix intersection — the patches after
+   * the hole were written against a view that had it. The content API cannot
+   * work out which those are (it has no schema), so the client sends the
+   * forward closure and it drops those memberships without deleting anything.
+   */
+  unstagePatchIds) {
     return fetch(`${this.contentUrl}/v1/${this.project}/patches`, {
       method: "DELETE",
       headers: {
@@ -7272,7 +8179,10 @@ class ValOpsHttp extends ValOps {
         "Content-Type": "application/json"
       },
       body: JSON.stringify({
-        patchIds
+        patchIds,
+        ...(unstagePatchIds !== undefined && unstagePatchIds.length > 0 ? {
+          unstagePatchIds
+        } : {})
       })
     }).then(async res => {
       if (res.ok) {
@@ -7311,7 +8221,22 @@ class ValOpsHttp extends ValOps {
       };
     });
   }
-  async commit(prepared, message, committer, filesDirectory, newBranch) {
+  async commit(prepared, message, committer, filesDirectory, newBranch,
+  /**
+   * The patch group this commit EMPTIES, if it empties one.
+   *
+   * The content API closes the group it is given — and closes it WITHOUT
+   * checking that the commit shipped all of it, so a caller that names a
+   * group still holding work takes those patches out of every group and
+   * leaves their author unable to publish them. The client therefore sends it
+   * only when the publish accounts for everything the group still holds.
+   *
+   * Omitting it is not neutral: the commit still empties the group (the
+   * content API drops applied ids from every group), but `published_at` is
+   * never set, so the id is reused across publishes instead of a new group
+   * per publish and the "already published" refusal can never fire.
+   */
+  patchGroupId) {
     try {
       var _res$headers$get3;
       const existingBranch = this.branch;
@@ -7319,12 +8244,45 @@ class ValOpsHttp extends ValOps {
         method: "POST",
         headers: {
           ...this.authHeaders,
+          /*
+           * WHO is publishing — the same `x-val-profile-id` stage and unstage
+           * send, and for the same reason: `this.authHeaders` is the app's API
+           * key, which names the PROJECT and not the person.
+           *
+           * Closing a group is an ownership decision, so the content API
+           * refuses a commit that names a `patchGroupId` it cannot attribute:
+           * without this header `profileId` is `undefined` there and every
+           * group-closing publish is 403 "Cannot resolve the caller's profile".
+           * That is the NORMAL full publish, not an edge — `publish` names the
+           * group whenever the commit empties it.
+           *
+           * Sent on every commit rather than only when a group is named. The
+           * committer is a person either way, `committer` in the body already
+           * says so, and a header that appears only on some commits is one more
+           * conditional for a reader of either repo to reconstruct. It changes
+           * nothing else: the content API reads it as an identity claim beside
+           * the app's key and derives no scope from it.
+           */
+          "x-val-profile-id": committer,
           "Content-Type": "application/json"
         },
         body: JSON.stringify({
           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,
@@ -7332,7 +8290,10 @@ class ValOpsHttp extends ValOps {
           committer,
           message,
           existingBranch,
-          newBranch
+          newBranch,
+          ...(patchGroupId !== undefined ? {
+            patchGroupId
+          } : {})
         })
       });
       if (res.ok) {
@@ -7369,19 +8330,620 @@ class ValOpsHttp extends ValOps {
           }
         };
       }
-      return {
-        error: {
-          message: "Could not commit. HTTP error: " + res.status + " " + res.statusText
-        }
+      return {
+        error: {
+          message: "Could not commit. HTTP error: " + res.status + " " + res.statusText
+        }
+      };
+    } catch (err) {
+      return {
+        error: {
+          message: `Could not commit (connection error?): ${err instanceof Error ? err.message : (err === null || err === void 0 ? void 0 : err.toString()) || "unknown error"}`
+        }
+      };
+    }
+  }
+
+  // #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 result.err({
+        kind: "transport",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    if (res.status === 404) {
+      return 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 = 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 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 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 result.err({
+        kind: "archive-unreadable",
+        commitSha: commitShaForErrors,
+        message: `unexpected response shape: ${fromError(parsed.error)}`
+      });
+    }
+    return result.ok(parsed.data);
+  }
+  async listCommits(branch, options) {
+    const params = new URLSearchParams({
+      branch
+    });
+    if ((options === null || options === void 0 ? void 0 : options.limit) !== undefined) {
+      params.set("limit", String(options.limit));
+    }
+    if ((options === null || options === void 0 ? void 0 : options.cursor) !== undefined) {
+      params.set("cursor", options.cursor);
+    }
+    const res = await this.getHistory(`/commits?${params}`, ListCommitsResponse, branch);
+    if (result.isErr(res)) {
+      return res;
+    }
+    return result.ok({
+      commits: res.value.commits,
+      nextCursor: res.value.nextCursor
+    });
+  }
+  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 (result.isErr(patchesRes)) {
+      return patchesRes;
+    }
+    return 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 (result.isErr(res)) {
+      return res;
+    }
+    return 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 (result.isErr(res)) {
+      return res;
+    }
+    return 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 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 result.err({
+        kind: "file-unavailable",
+        gitPath: filePath,
+        message: `${res.status} ${res.statusText}`
+      });
+    }
+    return 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 (result.isErr(patchesRes)) {
+    return patchesRes;
+  }
+  if (result.isErr(modulesRes)) {
+    return modulesRes;
+  }
+  if (result.isErr(filesRes)) {
+    return filesRes;
+  }
+  return 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 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 (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 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 : Internal.joinModuleFilePathAndModulePath(moduleFilePath, 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 (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
       };
-    } catch (err) {
-      return {
-        error: {
-          message: `Could not commit (connection error?): ${err instanceof Error ? err.message : (err === null || err === void 0 ? void 0 : err.toString()) || "unknown error"}`
-        }
+      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 = SerializedSchema.safeParse(version.schema);
+    if (!schemaRes.success) {
+      failures.push({
+        kind: "schema-unreadable",
+        moduleFilePath,
+        message: 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 (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 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 (result.isErr(res)) {
+    return res;
+  }
+  const version = res.value.modules.find(module => module.moduleFilePath === moduleFilePath);
+  if (version === undefined) {
+    return result.ok(null);
+  }
+  if (version.unavailable) {
+    return 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 = SerializedSchema.safeParse(version.schema);
+  if (!schemaRes.success) {
+    return result.ok({
+      source: version.source,
+      schema: null,
+      patchIds: [],
+      changedPaths: [],
+      failures: [{
+        kind: "schema-unreadable",
+        moduleFilePath,
+        message: fromError(schemaRes.error).toString()
+      }]
+    });
   }
+  return 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 || DEFAULT_CONTENT_HOST;
@@ -7539,31 +9101,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.
+ *
+ * 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.
  *
- * 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.
+ * 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,
@@ -8185,90 +9755,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.object({
-              member_role: z.union([z.literal("owner"), z.literal("developer"), z.literal("editor")]).optional(),
-              id: z.string(),
-              full_name: z.string().optional(),
-              username: z.string().optional(),
-              avatar_url: 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 = 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.object({
-              message: z.string()
-            }).safeParse(await fetchRes.json());
-            const message = getErrorMessageFromUnknownJson(json, "Unknown error");
-            return {
-              status: fetchRes.status,
-              json: {
-                message: message,
-                ...json
-              }
-            };
-          }
-        });
-      }
-    },
     "/logout": {
       GET: async req => {
         const query = req.query;
@@ -8577,10 +10063,190 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    //#region patch groups
+    // Staging and unstaging patches. Both take an already-closed set of patch ids:
+    // the prefix closure (staging) or the forward closure (unstaging) is computed
+    // on the client, which is the only side that has the schema needed to derive
+    // patch sets. See `docs/independent-publish/PLAN.md`.
+    //
+    // In FS mode there is no shared store and exactly one author, so group
+    // membership lives in the client and these handlers simply acknowledge. The
+    // client already sends an explicit patch id list to `/save`, so a locally-held
+    // group is enough to publish a subset correctly.
+    "/patch-groups/~/patches": {
+      PUT: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const {
+          patchGroupId,
+          patchIds
+        } = req.body;
+        const withPatchIds = req.body.withPatchIds ?? [];
+        if (serverOps instanceof ValOpsFS) {
+          return {
+            status: 200,
+            json: {
+              patchGroupId,
+              patchIds: [...patchIds, ...withPatchIds]
+            }
+          };
+        }
+        if (!("id" in auth) || !auth.id) {
+          return {
+            status: 401,
+            json: {
+              message: "Unauthorized"
+            }
+          };
+        }
+        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+        if (refusal !== null) {
+          return {
+            status: refusal.status,
+            json: {
+              message: refusal.message
+            }
+          };
+        }
+        const res = await serverOps.stagePatches(patchGroupId, patchIds, withPatchIds,
+        // Forwarded so the content API can refuse independently. This server
+        // has already refused a group that is not the caller's; sending the
+        // author means the check also holds for anything reaching the content
+        // API without coming through here.
+        auth.id);
+        if (res.error) {
+          return {
+            status: res.status,
+            json: {
+              message: res.error.message
+            }
+          };
+        }
+        return {
+          status: 200,
+          json: {
+            patchGroupId,
+            patchIds: res.patchIds
+          }
+        };
+      },
+      DELETE: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const {
+          patchGroupId,
+          patchIds
+        } = req.body;
+        const withPatchIds = req.body.withPatchIds ?? [];
+        if (serverOps instanceof ValOpsFS) {
+          return {
+            status: 200,
+            json: {
+              patchGroupId,
+              patchIds: [...patchIds, ...withPatchIds]
+            }
+          };
+        }
+        if (!("id" in auth) || !auth.id) {
+          return {
+            status: 401,
+            json: {
+              message: "Unauthorized"
+            }
+          };
+        }
+        const refusal = await refuseUnlessOwn(serverOps, patchGroupId, auth.id);
+        if (refusal !== null) {
+          return {
+            status: refusal.status,
+            json: {
+              message: refusal.message
+            }
+          };
+        }
+        const res = await serverOps.unstagePatches(patchGroupId, patchIds, withPatchIds, auth.id);
+        if (res.error) {
+          return {
+            status: res.status,
+            json: {
+              message: res.error.message
+            }
+          };
+        }
+        return {
+          status: 200,
+          json: {
+            patchGroupId,
+            patchIds: res.patchIds
+          }
+        };
+      }
+    },
     //#region patches
     "/patches": {
       PUT: async req => {
         const cookies = req.cookies;
+
+        /**
+         * Group membership travels WITH the patch, in one request.
+         *
+         * Atomic on purpose: the content API runs every refusal before its
+         * insert, so an invalid closure is a 400 with nothing written. Recording
+         * membership in a second call would let a patch exist outside its
+         * author's group whenever that call failed — and a patch outside your
+         * own group is one you cannot publish until a repair puts it back.
+         *
+         */
+        /*
+         * A membership is present if EITHER field is.
+         *
+         * The common case names no group: the content API resolves the author's
+         * open group, creating it if absent, so the client never has to hold an
+         * id across publishes. It still sends the closure, which is the part it
+         * alone can compute.
+         *
+         * `patchGroupId` is nullable, so an explicit `null` means "no group
+         * named" exactly as omitting it does — it is passed through as
+         * `undefined` rather than becoming a membership keyed by null.
+         */
+        const requestedPatchGroupId = req.body.patchGroupId ?? undefined;
+        const requestedWith = req.body.withPatchIds;
+        const patchGroup = requestedPatchGroupId !== undefined || requestedWith !== undefined ? {
+          ...(requestedPatchGroupId !== undefined ? {
+            patchGroupId: requestedPatchGroupId
+          } : {}),
+          withPatchIds: requestedWith ?? []
+        } : undefined;
+        if (patchGroup !== undefined && serverOps instanceof ValOpsFS) {
+          /*
+           * `fs` has no shared store and one author, so there is no group to
+           * join. Refused rather than acknowledged: answering 200 would tell the
+           * client its membership was recorded when it was dropped, and the
+           * client would then believe a publish is scoped when it is not.
+           */
+          return {
+            status: 400,
+            json: {
+              type: "patch-error",
+              message: "Patch groups are not available in fs mode. Omit the patch group fields.",
+              errors: {}
+            }
+          };
+        }
         const auth = getAuth(cookies);
         if (auth.error) {
           return {
@@ -8603,8 +10269,19 @@ const ValServer = (valModules, options, callbacks) => {
         const sessionId = req.body.sessionId ?? null;
         const authorId = "id" in auth ? auth.id : null;
         const newPatchIds = [];
+        /*
+         * The group the content API put these patches in.
+         *
+         * Every patch in one request has the same author and the same
+         * membership, so the last answer is the answer — they all land in the
+         * same group. Reported back because the client cannot learn it any
+         * other way: it names no group (the content API resolves the author's
+         * open one, creating it if absent), and the chain annotation is only
+         * re-read when a fetch has missing ids to ask for.
+         */
+        let patchGroupIdFromStore;
         for (const patch of patches) {
-          const createPatchRes = await serverOps.createPatch(patch.path, patch.patch, patch.patchId, parentRef, sessionId, authorId);
+          const createPatchRes = await serverOps.createPatch(patch.path, patch.patch, patch.patchId, parentRef, sessionId, authorId, patchGroup);
           if (result.isErr(createPatchRes)) {
             if (createPatchRes.error.errorType === "patch-head-conflict") {
               return {
@@ -8636,13 +10313,22 @@ const ValServer = (valModules, options, callbacks) => {
               patchId: createPatchRes.value.patchId
             };
             newPatchIds.push(createPatchRes.value.patchId);
+            if (createPatchRes.value.patchGroupId !== undefined) {
+              patchGroupIdFromStore = createPatchRes.value.patchGroupId;
+            }
           }
         }
         return {
           status: 200,
           json: {
             newPatchIds,
-            parentRef
+            parentRef,
+            // Absent rather than null where there are no groups: `fs` mode and
+            // a content API that predates them both answer without one, and the
+            // client reads absence as "staging is not available here".
+            ...(patchGroupIdFromStore !== undefined ? {
+              patchGroupId: patchGroupIdFromStore
+            } : {})
           }
         };
       },
@@ -8704,15 +10390,84 @@ const ValServer = (valModules, options, callbacks) => {
         }
         // TODO: we should sort by parentRef instead:
         patches.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        /**
+         * Patch groups, ANNOTATED onto the chain rather than filtering it.
+         *
+         * The client computes a new patch's parent as the last id in this
+         * response, so a filtered chain would make every client name a parent
+         * that is not the real head and `POST /patches` would answer 409
+         * forever. Annotate, never filter.
+         *
+         * Absent — not empty — where there are no groups: `fs` mode, a content
+         * API that predates them, or a failed lookup. The client reads absence
+         * as "this deployment has no groups" and leaves staging off, which is
+         * the behaviour every project has today. An empty array would say
+         * "groups exist and hold nothing", which would turn the staging UI on
+         * with everything held.
+         */
+        let patchGroups;
+        if (query.include_patch_groups === true && serverOps instanceof ValOpsHttp) {
+          /*
+           * FRESH, because this answer makes a CLOSING decision.
+           *
+           * The client adopts this annotation as its group membership and
+           * `emptiesOwnPatchGroup` then decides from it whether a publish may
+           * name the group — and the content API closes what it is named
+           * without checking. A one-second-old list is enough to get that
+           * wrong: the same author writing in a second tab joins the open
+           * group, the websocket pushes the chain immediately, so this tab's
+           * fetch for the missing patch lands well inside the cache window and
+           * reads a membership that is one patch short. It then publishes,
+           * names the group, and closes it with the other tab's work still in
+           * it — which leaves that tab wedged on 409 until a reload.
+           *
+           * `resolveOwnPatchScope` keeps the cache deliberately: that read
+           * decides what a draft render SHOWS, it is repeated once per
+           * `fetchVal` in a single render, and being a second stale there costs
+           * a patch appearing late rather than a group closing early.
+           */
+          const groupsRes = await serverOps.getPatchGroups({
+            fresh: true
+          });
+          if (groupsRes.status === "ok" && groupsRes.patchGroups.length > 0) {
+            patchGroups = groupsRes.patchGroups;
+          } else if (groupsRes.status === "error") {
+            // Not fatal: the chain is what this endpoint is for, and staging
+            // simply stays off for this read rather than the whole review
+            // screen failing to load.
+            console.error("Val: could not read patch groups", groupsRes.message);
+          }
+        }
+        const groupIdsByPatchId = new Map();
+        for (const group of patchGroups ?? []) {
+          for (const patchId of group.patchIds) {
+            const existing = groupIdsByPatchId.get(patchId);
+            if (existing) {
+              existing.push(group.patchGroupId);
+            } else {
+              groupIdsByPatchId.set(patchId, [group.patchGroupId]);
+            }
+          }
+        }
         return {
           status: 200,
           json: {
-            patches: patches,
+            patches: patches.map(patch => {
+              const patchGroupIds = groupIdsByPatchId.get(patch.patchId);
+              return patchGroupIds ? {
+                ...patch,
+                patchGroupIds
+              } : patch;
+            }),
+            ...(patchGroups ? {
+              patchGroups
+            } : {}),
             baseSha: await serverOps.getBaseSha()
           }
         };
       },
       DELETE: async req => {
+        var _req$body;
         const query = req.query;
         const cookies = req.cookies;
         const auth = getAuth(cookies);
@@ -8732,8 +10487,26 @@ const ValServer = (valModules, options, callbacks) => {
             }
           };
         }
-        const ids = query.id;
-        const deleteRes = await serverOps.deletePatches(ids);
+        const ids = query.id;
+        /*
+         * Which OTHER patches lose their group membership because these are
+         * going. Only the client can COMPUTE it — that needs the patch sets,
+         * which need the schema — but it is bounded here rather than trusted,
+         * because the content API strips those memberships from every group
+         * without an ownership check. See `boundUnstageClosure`.
+         *
+         * Only in `http` mode: `ValOpsFS` has no groups and ignores it, and the
+         * client does not send it there.
+         */
+        let unstagePatchIds;
+        const requestedUnstage = (_req$body = req.body) === null || _req$body === void 0 ? void 0 : _req$body.unstagePatchIds;
+        if (serverOps instanceof ValOpsHttp && requestedUnstage !== undefined && requestedUnstage.length > 0) {
+          const chain = await serverOps.fetchPatches({
+            excludePatchOps: true
+          });
+          unstagePatchIds = boundUnstageClosure(chain.patches, ids, requestedUnstage);
+        }
+        const deleteRes = await serverOps.deletePatches(ids, unstagePatchIds);
         if (deleteRes.errors && Object.keys(deleteRes.errors).length > 0) {
           console.error("Val: Failed to delete patches", deleteRes.errors);
           return {
@@ -8847,6 +10620,22 @@ const ValServer = (valModules, options, callbacks) => {
         } = req.query;
         // Defaults to true, mirroring /sources/~. The Studio opts out.
         const applyPatches = req.query.apply_patches !== false;
+        /*
+         * Whose pending work this render may see.
+         *
+         * The same resolution `/sources/~` runs, through the same function: a
+         * draft page renders module content and `jsonValues` entries together,
+         * and this route used to apply every pending patch on the branch while
+         * the modules beside it were scoped — so one screen showed the caller's
+         * view and everybody's unpublished work at once.
+         */
+        const {
+          ownPatchIds
+        } = await resolveOwnPatchScope(serverOps, {
+          explicitPatchIds: undefined,
+          ownGroupsOnly: req.query.own_patch_groups_only === true,
+          authorId: "id" in auth && auth.id || undefined
+        });
         const isWindow = offset !== undefined || limit !== undefined;
         const shapes = [key !== undefined, keys !== undefined, isWindow].filter(Boolean).length;
         if (shapes !== 1) {
@@ -8867,7 +10656,8 @@ const ValServer = (valModules, options, callbacks) => {
         }
         if (key !== undefined) {
           const res = await serverOps.getJsonEntry(moduleFilePath, key, {
-            applyPatches
+            applyPatches,
+            patchIds: ownPatchIds
           });
           if (res.status === "unauthorized") {
             return {
@@ -8908,7 +10698,8 @@ const ValServer = (valModules, options, callbacks) => {
           offset: offset,
           limit: limit
         }, {
-          applyPatches
+          applyPatches,
+          patchIds: ownPatchIds
         });
         if (res.status === "unauthorized") {
           return {
@@ -8993,10 +10784,87 @@ const ValServer = (valModules, options, callbacks) => {
           patches: []
         };
         if (query.exclude_patches !== true) {
-          patchOps = await serverOps.fetchPatches({
-            patchIds: undefined,
-            excludePatchOps: false
+          /**
+           * The caller's own groups, resolved from their session.
+           *
+           * A draft render cannot name its own group ids — it has no client
+           * state — so it asks for "mine" and the server works out which. Only
+           * when `patch_id` is absent: an explicit list is a caller that already
+           * knows what it wants.
+           *
+           * A group lookup that FAILS renders base rather than everything. Being
+           * shown only committed content while the content API is unreachable is
+           * a degraded preview; being shown another author's unpublished draft
+           * because a lookup failed is the bug this feature exists to prevent,
+           * and it would be silent.
+           */
+          const {
+            ownPatchIds,
+            scopeAlsoIncludesApplied
+          } = await resolveOwnPatchScope(serverOps, {
+            explicitPatchIds: query.patch_id,
+            ownGroupsOnly: query.own_patch_groups_only === true,
+            authorId: "id" in auth && auth.id || undefined
           });
+          const requestedPatchIds = query.patch_id ?? ownPatchIds;
+          if (scopeAlsoIncludesApplied) {
+            /*
+             * Scoped to this caller's groups, PLUS everything already
+             * committed.
+             *
+             * Filtered here rather than through `patchIds`, because the set is
+             * not knowable before the fetch: `appliedAt` lives on the patch,
+             * not on the group. One request either way — the whole chain is
+             * what the unscoped path fetches too — so this costs a filter, not
+             * a round trip.
+             *
+             * This also subsumes the empty-group case below: a caller holding
+             * nothing, on a branch with nothing applied, filters down to no
+             * patches, which is base.
+             */
+            const all = await serverOps.fetchPatches({
+              patchIds: undefined,
+              excludePatchOps: false
+            });
+            patchOps = {
+              ...all,
+              patches: scopedPatches(all.patches, ownPatchIds)
+            };
+          } else if (requestedPatchIds !== undefined && requestedPatchIds.length === 0) {
+            /*
+             * A group that holds nothing renders base, and is handled HERE.
+             *
+             * `fetchPatches` cannot express it: both implementations read an
+             * empty `patchIds` as "no filter" and return the whole chain
+             * (`ValOpsFS`: `patchIds.length > 0 ? new Set(...) : null`;
+             * `ValOpsHttp`: an explicit `length === 0` branch that fetches all).
+             * That is the right default for every caller that has ever passed a
+             * list, since none of them can mean "none" — but it is the most
+             * dangerous possible reading of an EXPLICITLY empty group, which
+             * would render every unpublished patch on the branch instead of
+             * base.
+             *
+             * Answered before the call rather than by changing that shared
+             * default, which seven other call sites rely on.
+             */
+            patchOps = {
+              patches: []
+            };
+          } else {
+            patchOps = await serverOps.fetchPatches({
+              /*
+               * The caller's patch group, when it named one.
+               *
+               * `undefined` means every pending patch, which is what every
+               * existing caller gets and has to keep getting. A draft-mode
+               * render that names its group gets base + that group instead, so
+               * a server-rendered preview shows the same thing the person
+               * editing is looking at rather than everybody's unpublished work.
+               */
+              patchIds: requestedPatchIds,
+              excludePatchOps: false
+            });
+          }
         }
         // We check authorization here, because it is the first call to the backend
         if (patchOps.error && patchOps.unauthorized) {
@@ -9253,6 +11121,43 @@ const ValServer = (valModules, options, callbacks) => {
          * store wholesale.
          */
         const consumed = patches.patches.map(patch => patch.patchId);
+        /*
+         * Has somebody else published since this was decided?
+         *
+         * The client names the newest commit it knew about; anything newer here
+         * means the review screen it acted on described a world that has moved.
+         * The answer is "look again" rather than "your commit was rejected".
+         *
+         * Git's own not-fast-forward guard cannot see this: the chain is
+         * fetched and committed fresh at this point, so the parent commit sent
+         * is always the server's current one.
+         *
+         * Checked HERE, before `analyzePatches` and `prepare`, rather than just
+         * before the commit: a publish that is going to be refused should not
+         * first pay to apply every patch in it. And compared against the
+         * commits `fetchPatches` just returned — `applicable/patches` filters
+         * its PATCHES by the requested ids and never its commits, so the second
+         * whole-chain fetch this used to make asked for a list it already had.
+         *
+         * Only when the client sends a head. One that does not publishes
+         * exactly as it did before, and this cannot start refusing publishes for
+         * a field it never sets.
+         */
+        if (serverOps instanceof ValOpsHttp) {
+          const expectedHead = body.expectedHeadCommitSha;
+          if (expectedHead !== undefined) {
+            const serverHead = newestCommitSha(patches.commits);
+            if (serverHead !== null && serverHead !== expectedHead) {
+              return {
+                status: 409,
+                json: {
+                  message: "Someone else published while you were reviewing. Nothing was published — open Review again to see what changed.",
+                  headMoved: true
+                }
+              };
+            }
+          }
+        }
         const analysis = serverOps.analyzePatches(patches.patches, patches.commits, commit);
         let preparedCommit = await serverOps.prepare({
           ...analysis,
@@ -9401,8 +11306,53 @@ 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.
+             *
+             * Stage and unstage go through `refuseUnlessOwn`; this route did
+             * not, and the content API's `postCommit` marks the group published
+             * on id alone with no author clause — so the id was trusted twice
+             * and checked nowhere. Any logged-in editor could name a colleague's
+             * open group and close it: their pending patches land in a closed
+             * group and in no open one, so a scoped draft render shows base for
+             * them, and their own tab still believes the group is open, so their
+             * next stage is refused with 409.
+             *
+             * Same hole as the stage/unstage one this branch already closed, one
+             * route over. The content API needs the same guard — this one is the
+             * convenience, that one is what actually holds.
+             */
+            if (body.patchGroupId !== undefined && body.patchGroupId !== null) {
+              const refusal = await refuseUnlessOwn(serverOps, body.patchGroupId, auth.id);
+              if (refusal !== null) {
+                return {
+                  status: refusal.status,
+                  json: {
+                    message: refusal.message,
+                    /*
+                     * Flagged, because a bare 409 here reads as git refusing
+                     * the commit — which is retryable, and this is the
+                     * opposite. `refuseUnlessOwn` answers 409 for one reason
+                     * only: the group has already been published, so its id
+                     * will never be writable again and retrying reproduces
+                     * this forever. The client forgets the id instead.
+                     */
+                    ...(refusal.status === 409 ? {
+                      patchGroupPublished: true
+                    } : {})
+                  }
+                };
+              }
+            }
             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");
+            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,
+            /*
+             * 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);
             if (commitRes.error) {
               console.error("Failed to commit", commitRes.error);
               if ("isNotFastForward" in commitRes && commitRes.isNotFastForward) {
@@ -9423,9 +11373,20 @@ const ValServer = (valModules, options, callbacks) => {
               };
             }
             // TODO: serverOps.markApplied(patchIds);
+            /*
+             * The new head, back to the client that made it.
+             *
+             * Nothing else tells it in time: `headCommitSha` moves on a `/stat`
+             * response, so until the next poll the client still believes the
+             * pre-publish head — and its next publish sent that as
+             * `expectedHeadCommitSha`, hit the check above against the commit it
+             * had itself just made, and was told somebody else had published.
+             */
             return {
               status: 200,
-              json: {} // TODO:
+              json: {
+                commitSha: commitRes.commit
+              }
             };
           }
           return {
@@ -10007,11 +11968,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,
@@ -10139,6 +12102,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 (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 (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 (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 (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;
@@ -10191,6 +12285,242 @@ const ValServer = (valModules, options, callbacks) => {
     }
   };
 };
+/**
+ * Refuse to touch a group that is not the caller's.
+ *
+ * Exported for `patchGroupOwnership.test.ts`: this is the whole of the
+ * authorization for stage and unstage, and nothing else in the process checks
+ * it, so it is worth testing as a policy rather than only through a route.
+ *
+ * `getAuth` only proves a session EXISTS; it says nothing about whose
+ * group this is. And the content API cannot decide either — every call
+ * from here carries the app's API key, not the editor's identity — so if
+ * this does not check, nothing does.
+ *
+ * `GET /patches?include_patch_groups=true` hands every editor the id and
+ * author of every open group on the branch, so without this any logged-in
+ * editor can unstage another author's patches (their next publish
+ * silently ships less) or stage into their group (it silently ships
+ * more). The 403 declared for this route in `ApiRoutes.ts` was
+ * unreachable.
+ *
+ * Fails CLOSED: if the groups cannot be read, the mutation is refused
+ * rather than allowed unverified.
+ */
+
+/**
+ * The patches a scoped draft render should apply: the caller's own group, plus
+ * everything already committed.
+ *
+ * Scoping is about PENDING work. A published patch stays in the chain with
+ * `appliedAt` set until the next deployment moves the base, and it is part of
+ * everyone's view in that window — the unscoped path applies it. Dropping it
+ * meant the moment somebody published, their own draft preview reverted the
+ * field they had just shipped, and nobody else saw it either until the deploy
+ * landed; anything written on top in that window is authored against content
+ * already stale on `main`.
+ *
+ * Keyed on `appliedAt` rather than on the group's `publishedAt`, because a
+ * PARTIAL publish leaves the group open with only some of its patches applied.
+ * Those are committed too, and no flag on the group names them.
+ *
+ * `undefined` scope is unscoped and never reaches here; an EMPTY scope is a
+ * caller holding nothing, and on a branch with nothing applied it correctly
+ * filters down to no patches, which renders base.
+ */
+function scopedPatches(patches, ownPatchIds) {
+  const own = new Set(ownPatchIds ?? []);
+  return patches.filter(patch => own.has(patch.patchId) || patch.appliedAt !== null);
+}
+
+/**
+ * Which of the client's `unstagePatchIds` this server is willing to forward.
+ *
+ * The forward closure of a discard is the client's to compute — it needs the
+ * patch sets, which need the schema — and it was being forwarded verbatim. But
+ * the content API removes those memberships from EVERY group with no ownership
+ * check, so any logged-in editor could strip arbitrary patches out of any other
+ * author's group by attaching them to a delete of one of their own throwaway
+ * patches. That is the outcome the 403 on `/patch-groups` exists to prevent,
+ * reached by a different door: their next publish silently ships less.
+ *
+ * Neither server can compute the true closure, but this one can BOUND it. A
+ * patch can only be invalidated by a delete if it was written after that delete
+ * — its paths were chosen against a view that had it — and if it is in the same
+ * module, since a patch set never spans two. Anything outside those bounds was
+ * not in the closure whatever the client says, so it is dropped rather than
+ * refused: the delete is still correct, and refusing the whole request over an
+ * over-broad extra would turn a discard into an error the user cannot act on.
+ *
+ * Exported for the test. Pure, and given the chain rather than fetching it, so
+ * the ordering it depends on is visible in the test rather than mocked.
+ */
+function boundUnstageClosure(/** The pending chain, in chain order, as `fetchPatches` returns it. */
+chain, deleted, requested) {
+  if (requested.length === 0) {
+    return [];
+  }
+  const positionOf = new Map();
+  const moduleOf = new Map();
+  chain.forEach((entry, index) => {
+    positionOf.set(entry.patchId, index);
+    moduleOf.set(entry.patchId, entry.path);
+  });
+  const doomed = new Set(deleted);
+  return requested.filter(patchId => {
+    // A patch being deleted anyway does not need its membership stripped
+    // separately, and naming one is how an over-broad list hides.
+    if (doomed.has(patchId)) return false;
+    const position = positionOf.get(patchId);
+    const moduleFilePath = moduleOf.get(patchId);
+    if (position === undefined || moduleFilePath === undefined) return false;
+    return deleted.some(deletedId => {
+      const deletedPosition = positionOf.get(deletedId);
+      if (deletedPosition === undefined) return false;
+      return position > deletedPosition && moduleOf.get(deletedId) === moduleFilePath;
+    });
+  });
+}
+
+/**
+ * Which pending patches this caller may see, when they asked for "only mine".
+ *
+ * Shared by `/sources/~` and `/json`, and it has to be: a draft page renders
+ * both, so two answers to "whose work is this" put one person's half-finished
+ * edit on another person's preview through whichever route was not scoped. That
+ * is exactly what happened — `/json` applied every pending patch on the branch
+ * while the module content beside it was scoped.
+ *
+ * `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) {
+  let ownPatchIds;
+  /** See where this is set: committed work is nobody's to hold back. */
+  let scopeAlsoIncludesApplied = false;
+  if (opts.explicitPatchIds === undefined && opts.ownGroupsOnly) {
+    if (serverOps instanceof ValOpsHttp && opts.authorId) {
+      const groupsRes = await serverOps.getPatchGroups();
+      if (groupsRes.status === "unsupported") {
+        /*
+         * A content API that PREDATES patch groups — the endpoint 404s.
+         *
+         * Unscoped, which is what those deployments do today and must
+         * keep doing. Reading this as a failure and rendering base
+         * would silently drop every pending patch from every draft
+         * preview on every existing http project — the exact opposite
+         * of "keeps working unchanged", and invisible to the reader.
+         */
+        ownPatchIds = undefined;
+      } else if (groupsRes.status === "error") {
+        /*
+         * We could not ask, and this deployment DOES have the endpoint.
+         * Render base rather than everything: a degraded preview is
+         * recoverable, showing another author's unpublished draft is
+         * not, and it would be silent.
+         */
+        ownPatchIds = [];
+      } else if (groupsRes.patchGroups.length === 0) {
+        /*
+         * The branch has no groups AT ALL, so this deployment is not
+         * using them — a content API that predates patch groups, or a
+         * project where nobody has staged anything since they existed.
+         *
+         * Unscoped, which is the behaviour every such project has
+         * today. Collapsing this into "your group is empty" would make
+         * every draft render base and silently drop all pending
+         * content, which is what happened before this branch: nothing
+         * writes a group yet, so EVERY project is in this state right
+         * now.
+         */
+        ownPatchIds = undefined;
+      } else {
+        /*
+         * Groups exist and none are this person's: they have staged
+         * nothing, and base is the honest answer. Distinct from the
+         * case above, which is why the two are not one expression.
+         */
+        ownPatchIds = groupsRes.patchGroups.filter(group => group.publishedAt === null && group.authorId === opts.authorId).flatMap(group => group.patchIds);
+        /*
+         * Scoping applies to PENDING work only. Anything already
+         * committed is part of everyone's view.
+         *
+         * A published patch stays in the chain with `appliedAt` set
+         * until the next deployment moves the base, and the unscoped
+         * path applies it. Filtering to open groups dropped it — so the
+         * moment someone published, their own draft preview reverted
+         * the field they had just shipped, and nobody else saw it
+         * either until the deploy landed. Anything written on top in
+         * that window is authored against content that is already
+         * stale on `main`.
+         *
+         * Unioned by `appliedAt` rather than by pulling in groups with
+         * a `publishedAt`, because a partial publish leaves the group
+         * OPEN with some of its patches applied — those are committed
+         * too, and no group flag names them.
+         */
+        scopeAlsoIncludesApplied = true;
+      }
+    } else {
+      /*
+       * fs mode, or a server with no groups: there is nothing to scope
+       * BY, and every pending patch is this one person's anyway. Left
+       * `undefined` so the existing "apply everything" path runs.
+       */
+      ownPatchIds = undefined;
+    }
+  }
+  return {
+    ownPatchIds,
+    scopeAlsoIncludesApplied
+  };
+}
+async function refuseUnlessOwn(ops, patchGroupId, authorId) {
+  /*
+   * Never from the cache. This answers "is this group yours", and a group is at
+   * its youngest exactly when the question is asked — the first write creates
+   * it and the shell flushes its queued stages the moment the save response
+   * names it. A cached list fetched a few hundred milliseconds earlier does not
+   * contain it, and every one of those stages was refused and dropped.
+   */
+  const groupsRes = await ops.getPatchGroups({
+    fresh: true
+  });
+  if (groupsRes.status !== "ok") {
+    return {
+      status: 500,
+      message: "Could not verify that this patch group is yours, so it was not changed."
+    };
+  }
+  const group = groupsRes.patchGroups.find(candidate => candidate.patchGroupId === patchGroupId);
+  if (group === undefined || group.authorId === null || group.authorId !== authorId) {
+    /*
+     * "Not found" and "not yours" are the SAME refusal on purpose: the route
+     * schema has no 404, and `GET /patches` already lists every group on the
+     * branch, so distinguishing them hides nothing and only adds a second
+     * message to keep consistent.
+     *
+     * A null author is a group written by an api key or a PAT. Nobody owns it,
+     * so nobody may stage into it — `null === null` must not read as a match.
+     */
+    return {
+      status: 403,
+      message: "You can only change your own patch group"
+    };
+  }
+  if (group.publishedAt !== null) {
+    /*
+     * Already shipped, so it can never be written again. The content API
+     * answers this too; refusing here saves the round trip and keeps the
+     * wording the same as every other refusal on this route.
+     */
+    return {
+      status: 409,
+      message: "Patch group is already published"
+    };
+  }
+  return null;
+}
 function verifyCallbackReq(stateCookie, queryParams) {
   if (typeof stateCookie !== "string") {
     return {
@@ -10401,6 +12731,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) {
@@ -10722,7 +13091,7 @@ function createValApiRouter(route, valServerPromise, convert) {
       }
       let bodyRes;
       try {
-        bodyRes = reqDefinition.body ? reqDefinition.body.safeParse(await req.json()) : {
+        bodyRes = reqDefinition.body ? reqDefinition.body.safeParse(await readJsonBody(req)) : {
           success: true,
           data: {}
         };
@@ -10801,6 +13170,33 @@ function formatZodErrorString(error) {
   const errors = fromError(error).toString();
   return errors.length > 640 ? `${errors.slice(0, 640)}...` : errors;
 }
+
+/**
+ * The request's JSON body, or `undefined` when it has none.
+ *
+ * `req.json()` THROWS on an empty body, and the router used to call it
+ * unconditionally for any route that declares a body — so the moment
+ * `DELETE /patches` gained an optional body, every caller that sent none got
+ * `400 Could not parse request body`. Declaring the schema `.optional()` did
+ * not help: the throw happens before zod is ever consulted. Six e2e tests went
+ * red on a helper doing exactly what the route still permits.
+ *
+ * Told apart by the request rather than by catching, so a body that IS sent and
+ * is malformed still fails: absent means no content type and nothing to read,
+ * and anything else is parsed and allowed to throw. A route whose schema
+ * requires a body is unaffected — it gets `undefined` and zod refuses it, with
+ * the same 400 as before, now naming the field.
+ */
+async function readJsonBody(req) {
+  if (req.headers.get("content-length") === "0") {
+    return undefined;
+  }
+  const text = await req.text();
+  if (text.length === 0) {
+    return undefined;
+  }
+  return JSON.parse(text);
+}
 function zodErrorResult(error, message) {
   return {
     status: 400,
@@ -11454,21 +13850,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++) {
@@ -11726,14 +14123,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.
  */
 
 /**
@@ -11768,17 +14168,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.
  *
@@ -11878,17 +14267,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") {
@@ -11902,18 +14299,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."
           }
         };
       }
@@ -11924,78 +14320,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 = 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
     };
   };
 }
@@ -12093,14 +14461,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
@@ -13629,6 +16001,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.
@@ -13651,7 +16042,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
@@ -14300,4 +16692,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, Service, VAL_SCOPE_READ, VAL_SCOPE_WRITE, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, authorIdFromVerifiedSubject, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, createValTools, currentFixHandlers, decodeJwtWithoutVerifying, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };
+export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, Service, VAL_SCOPE_READ, VAL_SCOPE_WRITE, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, authorIdFromVerifiedSubject, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, createValTools, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err$1 as 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$1 as ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };