@valbuild/server 0.120.4 → 0.121.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @valbuild/server
 
+## 0.121.0
+
+### Minor Changes
+
+- [#464](https://github.com/valbuild/val/pull/464) [`2bcc6fd`](https://github.com/valbuild/val/commit/2bcc6fdff8d668123e07e3c5e81ac6fa1436e47b) Thanks [@freekh](https://github.com/freekh)! - Add staging and unstaging of pending changes, so one person can publish a small fix without shipping somebody else's unfinished work.
+
+  A **patch group** is the set of patches one user has chosen to publish. It is not a patch _set_: a patch set is computed from the schema and says which patches must move together, while a patch group is curated and says which ones you want live.
+
+  A group holds its owner's own work plus whatever the closure entangled with it — not everything pending. **So Publish changes meaning on a shared branch: it ships your changes and what they depend on, instead of everything anybody has pending.** That is the feature. Unstaging goes further: hold one of your own changes back and it leaves both your preview and your publish, while still existing for everyone else.
+
+  The rule relating the two is that for every group and every patch set, the group's members within that patch set must form a prefix in patch-chain order. Staging a change therefore pulls in whatever preceded it in the same patch set; unstaging drops whatever was built on top of it. The compare view names what a toggle moves, and whose it is, rather than quietly enlarging or shrinking a publish.
+
+  Editing inside a region you are holding back is allowed, and the patches you were holding are loaded back in rather than the edit being refused. An earlier design made such a region read-only until it was staged again, because an author picks an array index while looking at their own view — so re-staging patches afterwards can shift the content under the path they just chose, and their edit lands on the wrong element cleanly, with every invariant intact and only the content wrong. That guard is not what ships. It is a rare shape in practice, since two people's edits mostly land in different routes, and refusing an edit for a reason the author cannot see is a worse everyday experience than the case it prevents. Instead the real result is shown immediately: the widened set is what the editor renders and what the compare view lists.
+
+  Also fixes a pre-existing bug in patch set grouping: patch set paths were compared with a raw string prefix test, and nothing terminates a path segment, so `?foobar/title` matched `?foo`. Deleting record key `foo` and retitling record key `foobar` were treated as one inseparable change. Previously that over-grouped two unrelated edits in the review screen; with staging it would have meant publishing a deletion nobody asked for.
+
+  The `/patches` routes gain optional patch group fields and `/patch-groups/~/patches` is new. This needs a content API that has patch groups. Filesystem mode keeps the group in the client, since it has a single author and already sends an explicit patch id list when publishing.
+
+  When a save pulls other people's changes in, you are told: a toast names how many and whose. There is no undo, because your edit was written against the view those changes produce and now depends on them — the compare view shows the widened set.
+
+  Two other things keep a session honest about a shared branch. `/stat` now says which pending changes have already been published, so another author's publish stops looking pending in your Studio the moment it lands rather than when the site redeploys. And Publish refuses, without writing anything, if somebody published while you were reviewing — the review screen you acted on described a branch that has since moved.
+
+  Two things this does **not** do yet, both of which need the group annotation to refresh on its own rather than only inside a fetch for missing patch ids:
+
+  - a stage or unstage in one tab does not reach another tab;
+  - if persisting a stage fails, the local view keeps it until the page is reloaded.
+
+  `docs/independent-publish/DESIGN.md` describes the model and lists what is still a judgement call.
+
+- [#605](https://github.com/valbuild/val/pull/605) [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79) Thanks [@freekh](https://github.com/freekh)! - `s.settings()`: the project's settings, as content.
+
+  A settings module is one per project, at the root of the content tree:
+
+  ```typescript
+  // settings.val.ts
+  export default c.define("/settings.val.ts", s.settings(), {});
+  ```
+
+  Register it in `val.modules.ts` like any other module, and it shows up in the
+  Studio under the cog at the foot of the left rail. Everything in it is content:
+  it is edited as a draft, it appears in the publish diff, and it is the same for
+  everyone working on the project.
+
+  Every key is optional, at every level, so `{}` is a complete settings module —
+  and stays one as sections are added. What it holds today is the assistant:
+
+  ```typescript
+  export default c.define("/settings.val.ts", s.settings(), {
+    assistant: {
+      enabled: true,
+      context: "A CMS for developers, run by a team of four in Oslo.",
+      tone: "Plain and direct. British English, sentence case in headings.",
+    },
+  });
+  ```
+
+  `context` is background the assistant would otherwise guess at; `tone` is how it
+  should write when it writes content. Both are sent with every message it makes.
+
+  `enabled` decides whether editors have an assistant, and it has **three** states
+  rather than two:
+
+  - `true` — they do.
+  - `false` — they do not, and every trace of it goes: no button in the top bar,
+    no row in the quick actions, no panel, nothing sent.
+  - unset — nobody has decided. The assistant is still **shown**, and asks to be
+    turned on before it is used. Hiding an assistant nobody has decided about
+    means nobody discovers it; quietly enabling one means a project starts sending
+    its content to a model because it did not know to say no.
+
+  A project with no settings module at all has an assistant, as before: there is
+  nowhere to record a decision, and nowhere for the prompt to write the answer.
+
+  **Breaking: `ai.chat` is gone from `val.config.ts`.** Whether the assistant is
+  available is a decision about the project's content, made by the people who edit
+  it, so it moved to settings — turning the chat on used to take a developer, a
+  deploy and a code review of a boolean. Remove the whole block:
+
+  ```diff
+   const { s, c, val, config } = initVal({
+  -  ai: {
+  -    chat: {
+  -      experimental: { enable: true },
+  -      suggestions: ["Summarize", "Fix typos at this page"],
+  -      title: "Ask me anything",
+  -      description: "Val can answer questions about the content.",
+  -    },
+  -  },
+   });
+  ```
+
+  `experimental.enable` becomes `assistant.enabled` in the settings module.
+  `suggestions`, `title` and `description` are removed with nothing replacing
+  them: the assistant now opens with its own copy. A project that had the chat
+  enabled and wants it to stay on for everyone should write
+  `assistant: { enabled: true }` — otherwise editors are offered it and asked.
+
+  `ai.commitMessages` stays in `val.config.ts`, and is unaffected.
+
+  Two settings modules, or one in a subdirectory, is a module error: the dev
+  server refuses to serve sources, `npx val validate` reports it against the file,
+  and the Studio says so rather than picking one.
+
+### Patch Changes
+
+- Updated dependencies [[`105479b`](https://github.com/valbuild/val/commit/105479b84a08846f1fe5971916f6a54275198d12), [`55ec736`](https://github.com/valbuild/val/commit/55ec73651394908b6f440e360d181b95a91c0a93), [`2bcc6fd`](https://github.com/valbuild/val/commit/2bcc6fdff8d668123e07e3c5e81ac6fa1436e47b), [`2bcbee1`](https://github.com/valbuild/val/commit/2bcbee1be682c2bbd5b7bc7d152ddd4204162fd2), [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79), [`2db27d5`](https://github.com/valbuild/val/commit/2db27d555441bee2dd31817acc8c92b7b718ee55)]:
+  - @valbuild/ui@0.121.0
+  - @valbuild/shared@0.121.0
+  - @valbuild/core@0.121.0
+
 ## 0.120.4
 
 ### Patch Changes

package/dist/declarations/src/Service.d.ts

@@ -14,6 +14,21 @@ export declare class Service {
      * The module file paths that are registered in the project's val.modules.
      */
     getModuleFilePaths(): ModuleFilePath[];
+    /**
+     * 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(): {
+        message: string;
+        path?: ModuleFilePath;
+    }[];
     private serializedSchemaOf;
     get(moduleFilePath: ModuleFilePath, modulePath: ModulePath, options?: {
         validate: boolean;

package/dist/declarations/src/ValOps.d.ts

@@ -220,8 +220,11 @@ export declare abstract class ValOps {
      * in-flight client patches the server has not seen) must pass
      * `applyPatches: false` or the same edits would be applied twice.
      */
-    getJsonEntry(moduleFilePath: ModuleFilePath, entryKey: string, opts?: {
+    getJsonEntry(moduleFilePath: ModuleFilePath, entryKey: string, 
+    /** Passed straight through — see {@link getJsonEntries}. */
+    opts?: {
         applyPatches?: boolean;
+        patchIds?: PatchId[];
     }): Promise<{
         status: "success";
         content: JSONValue | null;
@@ -260,6 +263,15 @@ export declare abstract class ValOps {
         limit: number;
     }, opts?: {
         applyPatches?: boolean;
+        /**
+         * Only these pending patches, or every one when `undefined`.
+         *
+         * A draft render is scoped to the caller's own groups, and a page renders
+         * `jsonValues` entries beside module content — so without this the two
+         * halves of one page disagreed about whose unpublished work they showed.
+         * `undefined` is what every other caller passes and must keep getting.
+         */
+        patchIds?: PatchId[];
     }): Promise<{
         status: "success";
         entries: {
@@ -362,10 +374,25 @@ export declare abstract class ValOps {
     readProjectFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;
-    createPatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef, sessionId: string | null, authorId: AuthorId | null): Promise<result.Result<{
+    createPatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef, sessionId: string | null, authorId: AuthorId | null, 
+    /**
+     * 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?: PatchGroupMembership): Promise<result.Result<{
         error?: undefined;
         patchId: PatchId;
         createdAt: string;
+        /** See {@link SaveSourceFilePatchResult} — absent where there are no groups. */
+        patchGroupId?: string;
     }, {
         errorType: "other";
         error: GenericErrorMessage;
@@ -377,7 +404,7 @@ export declare abstract class ValOps {
         patchIds?: PatchId[];
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
-    protected abstract saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef | null, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
+    protected abstract saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef | null, authorId: AuthorId | null, sessionId: string | null, patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     protected abstract getSourceFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;
@@ -414,8 +441,37 @@ export type GenericErrorMessage = {
     message: string;
     details?: unknown;
 };
+/**
+ * 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.
+ */
+export type PatchGroupMembership = {
+    /**
+     * Absent means "the author's open group, created if absent" — the content API
+     * resolves it. The client does not hold an id across publishes, because a
+     * published group is refused and the stale id would lose the write.
+     */
+    patchGroupId?: string;
+    withPatchIds: PatchId[];
+};
 export type SaveSourceFilePatchResult = result.Result<{
     patchId: PatchId;
+    /**
+     * The group the patch ended up in, where the store has groups at all.
+     *
+     * Absent in `fs` mode and against a content API that predates groups. The
+     * client uses it to learn the id of the group its own first write created.
+     */
+    patchGroupId?: string;
 }, ({
     errorType: "other";
 } & GenericErrorMessage) | {
@@ -523,6 +579,36 @@ export type PatchReadError = {
     parentPatchId: ParentPatchId;
     message: string;
 };
+/**
+ * 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.
+ */
+export declare function scopedModulePatches<T extends {
+    path: ModuleFilePath;
+    patchId: PatchId;
+    appliedAt: {
+        commitSha: CommitSha;
+    } | null;
+}>(patches: T[], moduleFilePath: ModuleFilePath, patchIds: PatchId[] | undefined): T[];
 export type OrderedPatches = {
     patches: {
         path: ModuleFilePath;

package/dist/declarations/src/ValOpsFS.d.ts

@@ -1,5 +1,5 @@
 import { PatchId, ModuleFilePath, ValModules } from "@valbuild/core";
-import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
+import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
 import { Patch, ParentRef, ValCommit } from "@valbuild/shared/internal";
 import { Buffer } from "buffer";
 export declare class ValOpsFS extends ValOps {
@@ -102,7 +102,7 @@ export declare class ValOpsFS extends ValOps {
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
     private parseJsonFile;
-    protected saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, _parentRef: ParentRef, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
+    protected saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, _parentRef: ParentRef, authorId: AuthorId | null, sessionId: string | null, _patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     protected getSourceFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;

package/dist/declarations/src/ValOpsHttp.d.ts

@@ -1,13 +1,22 @@
 import { type PatchId, type ModuleFilePath, ValModules } from "@valbuild/core";
 import type { Patch as PatchT, ParentRef as ParentRefT } from "@valbuild/core/patch";
-import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha } from "./ValOps.js";
+import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha } from "./ValOps.js";
 import { z } from "zod";
-import { ParentRef, ValCommit, ValDeployment } from "@valbuild/shared/internal";
+import { ParentRef, ValCommit, ValDeployment, type PatchGroupT } from "@valbuild/shared/internal";
 declare const PatchId: z.ZodString & z.ZodType<PatchId, string, z.core.$ZodTypeInternals<PatchId, string>>;
 declare const CommitSha: z.ZodString & z.ZodType<CommitSha, string, z.core.$ZodTypeInternals<CommitSha, string>>;
 declare const BaseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;
 declare const AuthorId: z.ZodString & z.ZodType<AuthorId, string, z.core.$ZodTypeInternals<AuthorId, string>>;
 declare const ModuleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+export type PatchGroupMutationResult = {
+    patchIds: PatchId[];
+    status?: undefined;
+    error?: undefined;
+} | {
+    patchIds: PatchId[];
+    status: 403 | 409 | 500;
+    error: GenericErrorMessage;
+};
 export declare class ValOpsHttp extends ValOps {
     private readonly contentUrl;
     private readonly project;
@@ -68,6 +77,10 @@ export declare class ValOpsHttp extends ValOps {
         commits: ValCommit[];
         deployments: ValDeployment[];
         patches: PatchId[];
+        /** Of `patches`, the ones that have shipped. See the implementation. */
+        appliedPatches: PatchId[];
+        /** The newest commit, which is the publish head. */
+        headCommitSha?: string;
     } | {
         type: "error";
         error: GenericErrorMessage;
@@ -92,7 +105,120 @@ export declare class ValOpsHttp extends ValOps {
         patchIds?: PatchId[];
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
-    protected saveSourceFilePatch(path: ModuleFilePath, patch: PatchT, patchId: PatchId, parentRef: ParentRefT, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
+    /**
+     * 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.
+     */
+    stagePatches(patchGroupId: string, 
+    /** What the user asked to stage. */
+    patchIds: PatchId[], 
+    /**
+     * 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: PatchId[], 
+    /**
+     * 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: AuthorId | null): Promise<PatchGroupMutationResult>;
+    /**
+     * 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.
+     */
+    unstagePatches(patchGroupId: string, 
+    /** What the user asked to unstage. */
+    patchIds: PatchId[], 
+    /** What has to go with it: everything built on top of it. */
+    withPatchIds: PatchId[], 
+    /** See {@link stagePatches} — the content API's half of the ownership check. */
+    authorId: AuthorId | null): Promise<PatchGroupMutationResult>;
+    /**
+     * 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.
+     */
+    private patchGroupsCache;
+    getPatchGroups(options?: {
+        /**
+         * Ask the content API even if a recent answer is remembered.
+         *
+         * For the checks that DECIDE something rather than render something.
+         * `refuseUnlessOwn` reads this list to say whether a group is yours, and a
+         * group is at its youngest exactly when that matters: the first write
+         * creates it, the save response names it, and the shell flushes its queued
+         * stages immediately — well inside the cache window. Served from a list
+         * fetched before the group existed, every one of those was refused 403 and
+         * dropped, so the queue that exists to survive the post-publish window
+         * persisted nothing in the flow it was built for.
+         *
+         * Not solved by shortening the window: the cache sits on this instance,
+         * which outlives the request, so "recent" is recent for the whole server
+         * and not for one render.
+         */
+        fresh?: boolean;
+    }): Promise<{
+        status: "ok";
+        patchGroups: PatchGroupT[];
+    } | {
+        status: "unsupported";
+    } | {
+        status: "error";
+        message: string;
+    }>;
+    private fetchPatchGroups;
+    private mutatePatchGroup;
+    protected saveSourceFilePatch(path: ModuleFilePath, patch: PatchT, patchId: PatchId, parentRef: ParentRefT, authorId: AuthorId | null, sessionId: string | null, patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     /**
      * @deprecated For HTTP ops use direct upload instead (i.e. client should upload the files directly) since hosting platforms (Vercel) might have low limits on the size of the request body.
      */
@@ -108,7 +234,17 @@ export declare class ValOpsHttp extends ValOps {
     getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, remote: boolean): Promise<Buffer | null>;
     protected getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, remote: boolean): Promise<OpsMetadata<T>>;
     protected getBinaryFileMetadata<T extends "file" | "image">(filePath: string, type: T): Promise<OpsMetadata<T>>;
-    deletePatches(patchIds: PatchId[]): Promise<{
+    deletePatches(patchIds: PatchId[], 
+    /**
+     * 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?: PatchId[]): Promise<{
         deleted: PatchId[];
         errors?: undefined;
         error?: undefined;
@@ -120,7 +256,22 @@ export declare class ValOpsHttp extends ValOps {
         errors?: undefined;
         deleted?: undefined;
     }>;
-    commit(prepared: PreparedCommit, message: string, committer: AuthorId, filesDirectory: string, newBranch?: string): Promise<{
+    commit(prepared: PreparedCommit, message: string, committer: AuthorId, filesDirectory: string, newBranch?: string, 
+    /**
+     * 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?: string): Promise<{
         isNotFastForward?: boolean;
         updatedFiles: string[];
         commit: CommitSha;

package/dist/declarations/src/ValServer.d.ts

@@ -1,6 +1,9 @@
-import { ValModules, ValConfig } from "@valbuild/core";
+import { ValModules, PatchId, ModuleFilePath, ValConfig } from "@valbuild/core";
 import { Api, ServerOf } from "@valbuild/shared/internal";
 import { z } from "zod";
+import { ValOpsFS } from "./ValOpsFS.js";
+import { CommitSha } from "./ValOps.js";
+import { ValOpsHttp } from "./ValOpsHttp.js";
 export type ValServerOptions = {
     route: string;
     valEnableRedirectUrl?: string;
@@ -33,6 +36,108 @@ export type ValServerCallbacks = {
     onEnable: (success: boolean) => Promise<void>;
     onDisable: (success: boolean) => Promise<void>;
 };
+/**
+ * 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.
+ */
+export declare function scopedPatches<T extends {
+    patchId: PatchId;
+    appliedAt: {
+        commitSha: CommitSha;
+    } | null;
+}>(patches: T[], ownPatchIds: PatchId[] | undefined): T[];
+/**
+ * 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.
+ */
+export declare function boundUnstageClosure(
+/** The pending chain, in chain order, as `fetchPatches` returns it. */
+chain: readonly {
+    patchId: PatchId;
+    path: ModuleFilePath;
+}[], deleted: readonly PatchId[], requested: readonly PatchId[]): PatchId[];
+/**
+ * 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.
+ */
+export declare function resolveOwnPatchScope(serverOps: ValOpsFS | ValOpsHttp, opts: {
+    /** A caller that named a list already knows what it wants. */
+    explicitPatchIds: PatchId[] | undefined;
+    ownGroupsOnly: boolean;
+    /** `undefined` where there is no session to have one. */
+    authorId: string | undefined;
+}): Promise<{
+    ownPatchIds: PatchId[] | undefined;
+    scopeAlsoIncludesApplied: boolean;
+}>;
+export declare function refuseUnlessOwn(ops: ValOpsHttp, patchGroupId: string, authorId: string): Promise<{
+    status: 403 | 409 | 500;
+    message: string;
+} | null>;
 declare const IntegratedServerJwtPayload: z.ZodObject<{
     sub: z.ZodString;
     exp: z.ZodNumber;