@valbuild/server 0.120.4 → 0.121.0

package/dist/valbuild-server.esm.js

@@ -8,7 +8,7 @@ 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, PatchGroup, newestCommitSha, 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';
@@ -1665,6 +1665,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];
   }
@@ -2362,7 +2377,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 +2472,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
       }));
@@ -3716,8 +3732,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,7 +3761,12 @@ 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
+      } : {})
     });
   }
 
@@ -3755,6 +3789,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 +3814,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 +5871,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,
@@ -6552,7 +6638,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 +6663,33 @@ const CommitResponse = z.object({
   commit: CommitSha,
   branch: z.string()
 });
+/*
+ * 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 +6849,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 +6891,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 +6981,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 +7018,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 +7047,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,7 +7161,281 @@ class ValOpsHttp extends ValOps {
       };
     }
   }
-  async saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId) {
+
+  // #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",
@@ -7006,7 +7453,24 @@ class ValOpsHttp extends ValOps {
         baseSha,
         commit: this.commitSha,
         branch: this.branch,
-        coreVersion: Internal.VERSION.core
+        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;
@@ -7014,7 +7478,21 @@ class ValOpsHttp extends ValOps {
         const parsed = SavePatchResponse.safeParse(await res.json());
         if (parsed.success) {
           return result.ok({
-            patchId: parsed.data.patchId
+            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({
@@ -7264,7 +7742,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 +7760,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 +7802,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,6 +7825,26 @@ 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({
@@ -7332,7 +7858,10 @@ class ValOpsHttp extends ValOps {
           committer,
           message,
           existingBranch,
-          newBranch
+          newBranch,
+          ...(patchGroupId !== undefined ? {
+            patchGroupId
+          } : {})
         })
       });
       if (res.ok) {
@@ -8577,10 +9106,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 +9312,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 +9356,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 +9433,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);
@@ -8733,7 +9531,25 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         const ids = query.id;
-        const deleteRes = await serverOps.deletePatches(ids);
+        /*
+         * 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 +9663,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 +9699,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 +9741,8 @@ const ValServer = (valModules, options, callbacks) => {
           offset: offset,
           limit: limit
         }, {
-          applyPatches
+          applyPatches,
+          patchIds: ownPatchIds
         });
         if (res.status === "unauthorized") {
           return {
@@ -8993,10 +9827,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 +10164,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 +10349,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 +10416,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 {
@@ -10191,6 +11195,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 {
@@ -10722,7 +11962,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 +12041,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,