@valbuild/shared 0.129.0 → 0.133.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @valbuild/shared
 
+## 0.133.0
+
+### Minor Changes
+
+- [#700](https://github.com/valbuild/val/pull/700) [`802412b`](https://github.com/valbuild/val/commit/802412b92c06bc1abbca78c86885e39c8710dd83) Thanks [@freekh](https://github.com/freekh)! - http mode no longer needs a git repository
+
+  A Val app can now run in http mode with no commit and no branch — its content
+  service is the store of record, and git is an optional mirror of the code. This
+  is what `fs` mode has always done: it has never had git, and it works.
+
+  Before this, `VAL_API_KEY` and `VAL_SECRET` were not enough. `VAL_GIT_COMMIT`
+  and `VAL_GIT_BRANCH` were required too, so a deployment with no commit to name
+  either threw at boot or fell through to `fs` mode and reached for a working
+  tree that was not there.
+
+  **Breaking, if you pass `http` options in code.** `gitCommit` and `gitBranch`
+  are replaced by one optional `git`:
+
+  ```diff
+   initValServer(valModules, config, {
+     http: {
+       apiKey,
+       valSecret,
+  -    gitCommit: process.env.VAL_GIT_COMMIT,
+  -    gitBranch: "main",
+  +    // Only for a project whose content is mirrored into a repository.
+  +    // Omit it entirely otherwise.
+  +    git: { commit: process.env.VAL_GIT_COMMIT, branch: "main" },
+     },
+   })
+  ```
+
+  `VAL_GIT_COMMIT` and `VAL_GIT_BRANCH` still work and are still read; they are
+  simply no longer required. Set both or neither — a commit without a branch, or
+  a branch without a commit, is refused at startup with a message naming the
+  missing half, rather than failing later at a publish.
+
+  **What a commit is for, where you have one.** Turning pending patches into new
+  `.val.ts` text means reading the current text first, and that read goes to the
+  content service at that commit. It is the publish path, not the serving path: a
+  committed render reads the source compiled into the build and asks the content
+  service nothing. With no repository there is nothing to write `.val.ts` into,
+  so a publish records the module's data and its schema and skips the file — and
+  that data is what history reads, so nothing is lost.
+
+  **A publish can now be refused by name, before it is attempted.** If a project
+  mirrors its commits into a repository but the running deployment was built
+  before that repository existed, it has no commit to write the mirror against.
+  Publishing anyway would save the content and silently leave the repository
+  behind. The Studio now disables Publish and shows why, and `/save` refuses with
+  a `no-base` code instead of failing partway.
+
+  **Also:** `ValCommit` and `HistoricalCommit` have nullable `parentCommitSha`
+  and `clientCommitSha`, and `/stat`'s `commitSha` is optional. A root commit has
+  no parent, and a publisher with no repository does not report where it was. If
+  you read these fields, handle `null`.
+
+## 0.130.0
+
+### Patch Changes
+
+- Updated dependencies [[`8425378`](https://github.com/valbuild/val/commit/8425378c315ea46b5d822f1130b633e0449ff1b0), [`473a185`](https://github.com/valbuild/val/commit/473a185f70351b44388f3bc1852649e2c1dbe001), [`64f0de3`](https://github.com/valbuild/val/commit/64f0de339b8621cb5a6c422dfe55cae5b2bbe2a0)]:
+  - @valbuild/core@0.130.0
+
 ## 0.129.0
 
 ### Minor Changes

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -423,6 +423,10 @@ export declare const Api: {
                     profileId: z.ZodNullable<z.ZodString>;
                     mode: z.ZodUnion<readonly [z.ZodLiteral<"http">, z.ZodLiteral<"fs">]>;
                     jsonEntriesSha: z.ZodOptional<z.ZodString>;
+                    publishRefusal: z.ZodOptional<z.ZodObject<{
+                        code: z.ZodLiteral<"no-base">;
+                        message: z.ZodString;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"use-websocket">;
                     url: z.ZodString;
@@ -430,14 +434,14 @@ export declare const Api: {
                     baseSha: z.ZodString;
                     schemaSha: z.ZodString;
                     sourcesSha: z.ZodString;
-                    commitSha: z.ZodString;
+                    commitSha: z.ZodOptional<z.ZodString>;
                     patches: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
                     appliedPatches: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
                     headCommitSha: z.ZodOptional<z.ZodString>;
                     commits: z.ZodArray<z.ZodObject<{
                         commitSha: z.ZodString;
-                        clientCommitSha: z.ZodString;
-                        parentCommitSha: z.ZodString;
+                        clientCommitSha: z.ZodNullable<z.ZodString>;
+                        parentCommitSha: z.ZodNullable<z.ZodString>;
                         branch: z.ZodString;
                         creator: z.ZodString;
                         createdAt: z.ZodString;
@@ -462,6 +466,10 @@ export declare const Api: {
                     }, z.core.$strip>;
                     profileId: z.ZodNullable<z.ZodString>;
                     mode: z.ZodUnion<readonly [z.ZodLiteral<"http">, z.ZodLiteral<"fs">]>;
+                    publishRefusal: z.ZodOptional<z.ZodObject<{
+                        code: z.ZodLiteral<"no-base">;
+                        message: z.ZodString;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>]>;
             }, z.core.$strip>]>;
         };
@@ -1029,6 +1037,12 @@ export declare const Api: {
                 status: z.ZodLiteral<409>;
                 json: z.ZodUnion<readonly [z.ZodObject<{
                     message: z.ZodString;
+                    publishRefusal: z.ZodObject<{
+                        code: z.ZodLiteral<"no-base">;
+                        message: z.ZodString;
+                    }, z.core.$strip>;
+                }, z.core.$strip>, z.ZodObject<{
+                    message: z.ZodString;
                 }, z.core.$strip>, z.ZodObject<{
                     message: z.ZodString;
                     isNotFastForward: z.ZodLiteral<true>;
@@ -1106,8 +1120,8 @@ export declare const Api: {
                 json: z.ZodObject<{
                     commits: z.ZodArray<z.ZodObject<{
                         commitSha: z.ZodString;
-                        parentCommitSha: z.ZodString;
-                        clientCommitSha: z.ZodString;
+                        parentCommitSha: z.ZodNullable<z.ZodString>;
+                        clientCommitSha: z.ZodNullable<z.ZodString>;
                         branch: z.ZodString;
                         createdBranch: z.ZodNullable<z.ZodString>;
                         creator: z.ZodNullable<z.ZodString>;
@@ -1164,8 +1178,8 @@ export declare const Api: {
                 json: z.ZodObject<{
                     commit: z.ZodObject<{
                         commitSha: z.ZodString;
-                        parentCommitSha: z.ZodString;
-                        clientCommitSha: z.ZodString;
+                        parentCommitSha: z.ZodNullable<z.ZodString>;
+                        clientCommitSha: z.ZodNullable<z.ZodString>;
                         branch: z.ZodString;
                         createdBranch: z.ZodNullable<z.ZodString>;
                         creator: z.ZodNullable<z.ZodString>;

package/dist/declarations/src/internal/emptyOf.d.ts

@@ -1,4 +1,5 @@
-import { SerializedSchema, Json } from "@valbuild/core";
+import { SerializedSchema } from "@valbuild/core";
+import { JSONValue } from "@valbuild/core/patch";
 /**
  * What `emptyOf` cannot read off a serialized schema.
  *
@@ -22,4 +23,16 @@ export type EmptyOfContext = {
      */
     selectedLocale?: string;
 };
-export declare function emptyOf(schema: SerializedSchema, context?: EmptyOfContext): Json;
+/**
+ * The empty value for a schema — the thing a "create this" affordance writes.
+ *
+ * Returns `JSONValue`, the MUTABLE shape, rather than `Json`. Every value here
+ * is built fresh on the way out — `Object.fromEntries`, a new array, a
+ * primitive — and none of it aliases anything a caller could then mutate out
+ * from under someone. Saying `Json` instead made the type readonly, which is
+ * a claim about sharing that is not true of anything this returns, and left
+ * every caller asserting `as JSONValue` at the point of writing a patch. A
+ * `JSONValue` is still assignable to `Json`, so a reader of the value loses
+ * nothing.
+ */
+export declare function emptyOf(schema: SerializedSchema, context?: EmptyOfContext): JSONValue;

package/dist/declarations/src/internal/zod/History.d.ts

@@ -40,8 +40,8 @@ export declare const HistoryError: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type HistoryError = z.infer<typeof HistoryError>;
 export declare const HistoricalCommit: z.ZodObject<{
     commitSha: z.ZodString;
-    parentCommitSha: z.ZodString;
-    clientCommitSha: z.ZodString;
+    parentCommitSha: z.ZodNullable<z.ZodString>;
+    clientCommitSha: z.ZodNullable<z.ZodString>;
     branch: z.ZodString;
     createdBranch: z.ZodNullable<z.ZodString>;
     creator: z.ZodNullable<z.ZodString>;
@@ -97,8 +97,8 @@ export type HistoricalModule = z.infer<typeof HistoricalModule>;
 export declare const HistoricalPatchSet: z.ZodObject<{
     commit: z.ZodObject<{
         commitSha: z.ZodString;
-        parentCommitSha: z.ZodString;
-        clientCommitSha: z.ZodString;
+        parentCommitSha: z.ZodNullable<z.ZodString>;
+        clientCommitSha: z.ZodNullable<z.ZodString>;
         branch: z.ZodString;
         createdBranch: z.ZodNullable<z.ZodString>;
         creator: z.ZodNullable<z.ZodString>;

package/dist/declarations/src/internal/zod/ValCommit.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const ValCommit: z.ZodObject<{
     commitSha: z.ZodString;
-    clientCommitSha: z.ZodString;
-    parentCommitSha: z.ZodString;
+    clientCommitSha: z.ZodNullable<z.ZodString>;
+    parentCommitSha: z.ZodNullable<z.ZodString>;
     branch: z.ZodString;
     creator: z.ZodString;
     createdAt: z.ZodString;

package/internal/dist/valbuild-shared-internal.cjs.dev.js

@@ -1220,8 +1220,16 @@ var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSch
 
 var ValCommit = zod.z.object({
   commitSha: zod.z.string(),
-  clientCommitSha: zod.z.string(),
-  parentCommitSha: zod.z.string(),
+  /**
+   * Where the publisher said it was, or `null` when it did not say.
+   *
+   * Nullable since the content service mints its own commit shas rather than
+   * taking git's: most publishers no longer bake a commit at all, and a root
+   * commit -- the first publish of a project with no repository -- has no
+   * parent for the same reason.
+   */
+  clientCommitSha: zod.z.string().nullable(),
+  parentCommitSha: zod.z.string().nullable(),
   branch: zod.z.string(),
   creator: zod.z.string(),
   createdAt: zod.z.string(),
@@ -1293,8 +1301,10 @@ var HistoryError = zod.z.discriminatedUnion("kind", [zod.z.object({
 })]);
 var HistoricalCommit = zod.z.object({
   commitSha: zod.z.string(),
-  parentCommitSha: zod.z.string(),
-  clientCommitSha: zod.z.string(),
+  /** `null` for a root commit. See `ValCommit`. */
+  parentCommitSha: zod.z.string().nullable(),
+  /** `null` when the publisher did not say where it was. See `ValCommit`. */
+  clientCommitSha: zod.z.string().nullable(),
   branch: zod.z.string(),
   createdBranch: zod.z.string().nullable(),
   creator: zod.z.string().nullable(),
@@ -1415,6 +1425,27 @@ var GenericError = zod.z.object({
   message: zod.z.string()
 });
 
+/**
+ * Why a publish cannot happen, in a form the Studio can show.
+ *
+ * Carried on `/stat` so the action is disabled with the reason beside it, and
+ * on `/save`'s 409 so the same answer is given to a client that asked anyway --
+ * a stat can be a poll out of date, and nothing may reach the commit path on a
+ * project this deployment cannot publish.
+ *
+ * `no-base` is the only code so far: there is nowhere for this publish's
+ * commit to be based. Note which way round that is. A project whose content
+ * service is the store of record always HAS a base -- the service's own chain,
+ * which mints its own shas -- so this is not about a missing git repository.
+ * It is about a deployment that cannot do what its project requires: one built
+ * before the project attached a repository, now asked to mirror commits into
+ * one it knows no commit for.
+ */
+var PublishRefusal = zod.z.object({
+  code: zod.z.literal("no-base"),
+  message: zod.z.string()
+});
+
 /**
  * A patch group: the set of patches one user has chosen to publish.
  *
@@ -1810,7 +1841,8 @@ var Api = {
           config: ValConfig,
           profileId: zod.z.string().nullable(),
           mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")]),
-          jsonEntriesSha: zod.z.string().optional()
+          jsonEntriesSha: zod.z.string().optional(),
+          publishRefusal: PublishRefusal.optional()
         }), zod.z.object({
           type: zod.z.literal("use-websocket"),
           url: zod.z.string(),
@@ -1818,7 +1850,16 @@ var Api = {
           baseSha: zod.z.string(),
           schemaSha: zod.z.string(),
           sourcesSha: zod.z.string(),
-          commitSha: zod.z.string(),
+          /**
+           * The commit this deployment was built from.
+           *
+           * Optional: a project whose content service is the store of
+           * record has no repository and no commit baked into its build.
+           * The Studio has always parsed this as optional -- see
+           * `useStatus` -- and shows a branch and a commit only when there
+           * is one.
+           */
+          commitSha: zod.z.string().optional(),
           patches: zod.z.array(PatchId),
           /**
            * Of `patches`, the ones that have already SHIPPED.
@@ -1862,7 +1903,8 @@ var Api = {
           deployments: zod.z.array(ValDeployment).optional(),
           config: ValConfig,
           profileId: zod.z.string().nullable(),
-          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")])
+          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")]),
+          publishRefusal: PublishRefusal.optional()
         })])
       })])
     }
@@ -2383,7 +2425,19 @@ var Api = {
         json: GenericError
       }), zod.z.object({
         status: zod.z.literal(409),
-        json: zod.z.union([/** A group that has already shipped. See the 403 above. */
+        json: zod.z.union([
+        /*
+         * This deployment cannot publish this project at all.
+         *
+         * First in the union so it is read before the bare
+         * `{ message }` above it would swallow it. `/stat` carries the
+         * same refusal, so a Studio that is up to date never sends a save
+         * that lands here -- this is for the one that is a poll behind.
+         */
+        zod.z.object({
+          message: zod.z.string(),
+          publishRefusal: PublishRefusal
+        }), /** A group that has already shipped. See the 403 above. */
         zod.z.object({
           message: zod.z.string()
         }), zod.z.object({
@@ -4610,6 +4664,18 @@ function clampDateTimeString(value, options) {
  * validation then reports, rather than wrong ones.
  */
 
+/**
+ * The empty value for a schema — the thing a "create this" affordance writes.
+ *
+ * Returns `JSONValue`, the MUTABLE shape, rather than `Json`. Every value here
+ * is built fresh on the way out — `Object.fromEntries`, a new array, a
+ * primitive — and none of it aliases anything a caller could then mutate out
+ * from under someone. Saying `Json` instead made the type readonly, which is
+ * a claim about sharing that is not true of anything this returns, and left
+ * every caller asserting `as JSONValue` at the point of writing a patch. A
+ * `JSONValue` is still assignable to `Json`, so a reader of the value loses
+ * nothing.
+ */
 function emptyOf(schema, context) {
   if (schema.type === "object") {
     return Object.fromEntries(Object.keys(schema.items).map(function (key) {

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -1220,8 +1220,16 @@ var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSch
 
 var ValCommit = zod.z.object({
   commitSha: zod.z.string(),
-  clientCommitSha: zod.z.string(),
-  parentCommitSha: zod.z.string(),
+  /**
+   * Where the publisher said it was, or `null` when it did not say.
+   *
+   * Nullable since the content service mints its own commit shas rather than
+   * taking git's: most publishers no longer bake a commit at all, and a root
+   * commit -- the first publish of a project with no repository -- has no
+   * parent for the same reason.
+   */
+  clientCommitSha: zod.z.string().nullable(),
+  parentCommitSha: zod.z.string().nullable(),
   branch: zod.z.string(),
   creator: zod.z.string(),
   createdAt: zod.z.string(),
@@ -1293,8 +1301,10 @@ var HistoryError = zod.z.discriminatedUnion("kind", [zod.z.object({
 })]);
 var HistoricalCommit = zod.z.object({
   commitSha: zod.z.string(),
-  parentCommitSha: zod.z.string(),
-  clientCommitSha: zod.z.string(),
+  /** `null` for a root commit. See `ValCommit`. */
+  parentCommitSha: zod.z.string().nullable(),
+  /** `null` when the publisher did not say where it was. See `ValCommit`. */
+  clientCommitSha: zod.z.string().nullable(),
   branch: zod.z.string(),
   createdBranch: zod.z.string().nullable(),
   creator: zod.z.string().nullable(),
@@ -1415,6 +1425,27 @@ var GenericError = zod.z.object({
   message: zod.z.string()
 });
 
+/**
+ * Why a publish cannot happen, in a form the Studio can show.
+ *
+ * Carried on `/stat` so the action is disabled with the reason beside it, and
+ * on `/save`'s 409 so the same answer is given to a client that asked anyway --
+ * a stat can be a poll out of date, and nothing may reach the commit path on a
+ * project this deployment cannot publish.
+ *
+ * `no-base` is the only code so far: there is nowhere for this publish's
+ * commit to be based. Note which way round that is. A project whose content
+ * service is the store of record always HAS a base -- the service's own chain,
+ * which mints its own shas -- so this is not about a missing git repository.
+ * It is about a deployment that cannot do what its project requires: one built
+ * before the project attached a repository, now asked to mirror commits into
+ * one it knows no commit for.
+ */
+var PublishRefusal = zod.z.object({
+  code: zod.z.literal("no-base"),
+  message: zod.z.string()
+});
+
 /**
  * A patch group: the set of patches one user has chosen to publish.
  *
@@ -1810,7 +1841,8 @@ var Api = {
           config: ValConfig,
           profileId: zod.z.string().nullable(),
           mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")]),
-          jsonEntriesSha: zod.z.string().optional()
+          jsonEntriesSha: zod.z.string().optional(),
+          publishRefusal: PublishRefusal.optional()
         }), zod.z.object({
           type: zod.z.literal("use-websocket"),
           url: zod.z.string(),
@@ -1818,7 +1850,16 @@ var Api = {
           baseSha: zod.z.string(),
           schemaSha: zod.z.string(),
           sourcesSha: zod.z.string(),
-          commitSha: zod.z.string(),
+          /**
+           * The commit this deployment was built from.
+           *
+           * Optional: a project whose content service is the store of
+           * record has no repository and no commit baked into its build.
+           * The Studio has always parsed this as optional -- see
+           * `useStatus` -- and shows a branch and a commit only when there
+           * is one.
+           */
+          commitSha: zod.z.string().optional(),
           patches: zod.z.array(PatchId),
           /**
            * Of `patches`, the ones that have already SHIPPED.
@@ -1862,7 +1903,8 @@ var Api = {
           deployments: zod.z.array(ValDeployment).optional(),
           config: ValConfig,
           profileId: zod.z.string().nullable(),
-          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")])
+          mode: zod.z.union([zod.z.literal("http"), zod.z.literal("fs")]),
+          publishRefusal: PublishRefusal.optional()
         })])
       })])
     }
@@ -2383,7 +2425,19 @@ var Api = {
         json: GenericError
       }), zod.z.object({
         status: zod.z.literal(409),
-        json: zod.z.union([/** A group that has already shipped. See the 403 above. */
+        json: zod.z.union([
+        /*
+         * This deployment cannot publish this project at all.
+         *
+         * First in the union so it is read before the bare
+         * `{ message }` above it would swallow it. `/stat` carries the
+         * same refusal, so a Studio that is up to date never sends a save
+         * that lands here -- this is for the one that is a poll behind.
+         */
+        zod.z.object({
+          message: zod.z.string(),
+          publishRefusal: PublishRefusal
+        }), /** A group that has already shipped. See the 403 above. */
         zod.z.object({
           message: zod.z.string()
         }), zod.z.object({
@@ -4610,6 +4664,18 @@ function clampDateTimeString(value, options) {
  * validation then reports, rather than wrong ones.
  */
 
+/**
+ * The empty value for a schema — the thing a "create this" affordance writes.
+ *
+ * Returns `JSONValue`, the MUTABLE shape, rather than `Json`. Every value here
+ * is built fresh on the way out — `Object.fromEntries`, a new array, a
+ * primitive — and none of it aliases anything a caller could then mutate out
+ * from under someone. Saying `Json` instead made the type readonly, which is
+ * a claim about sharing that is not true of anything this returns, and left
+ * every caller asserting `as JSONValue` at the point of writing a patch. A
+ * `JSONValue` is still assignable to `Json`, so a reader of the value loses
+ * nothing.
+ */
 function emptyOf(schema, context) {
   if (schema.type === "object") {
     return Object.fromEntries(Object.keys(schema.items).map(function (key) {

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1213,8 +1213,16 @@ var SerializedSchema = z.union([SerializedStringSchema, SerializedLiteralSchema,
 
 var ValCommit = z.object({
   commitSha: z.string(),
-  clientCommitSha: z.string(),
-  parentCommitSha: z.string(),
+  /**
+   * Where the publisher said it was, or `null` when it did not say.
+   *
+   * Nullable since the content service mints its own commit shas rather than
+   * taking git's: most publishers no longer bake a commit at all, and a root
+   * commit -- the first publish of a project with no repository -- has no
+   * parent for the same reason.
+   */
+  clientCommitSha: z.string().nullable(),
+  parentCommitSha: z.string().nullable(),
   branch: z.string(),
   creator: z.string(),
   createdAt: z.string(),
@@ -1286,8 +1294,10 @@ var HistoryError = z.discriminatedUnion("kind", [z.object({
 })]);
 var HistoricalCommit = z.object({
   commitSha: z.string(),
-  parentCommitSha: z.string(),
-  clientCommitSha: z.string(),
+  /** `null` for a root commit. See `ValCommit`. */
+  parentCommitSha: z.string().nullable(),
+  /** `null` when the publisher did not say where it was. See `ValCommit`. */
+  clientCommitSha: z.string().nullable(),
   branch: z.string(),
   createdBranch: z.string().nullable(),
   creator: z.string().nullable(),
@@ -1408,6 +1418,27 @@ var GenericError = z.object({
   message: z.string()
 });
 
+/**
+ * Why a publish cannot happen, in a form the Studio can show.
+ *
+ * Carried on `/stat` so the action is disabled with the reason beside it, and
+ * on `/save`'s 409 so the same answer is given to a client that asked anyway --
+ * a stat can be a poll out of date, and nothing may reach the commit path on a
+ * project this deployment cannot publish.
+ *
+ * `no-base` is the only code so far: there is nowhere for this publish's
+ * commit to be based. Note which way round that is. A project whose content
+ * service is the store of record always HAS a base -- the service's own chain,
+ * which mints its own shas -- so this is not about a missing git repository.
+ * It is about a deployment that cannot do what its project requires: one built
+ * before the project attached a repository, now asked to mirror commits into
+ * one it knows no commit for.
+ */
+var PublishRefusal = z.object({
+  code: z.literal("no-base"),
+  message: z.string()
+});
+
 /**
  * A patch group: the set of patches one user has chosen to publish.
  *
@@ -1803,7 +1834,8 @@ var Api = {
           config: ValConfig,
           profileId: z.string().nullable(),
           mode: z.union([z.literal("http"), z.literal("fs")]),
-          jsonEntriesSha: z.string().optional()
+          jsonEntriesSha: z.string().optional(),
+          publishRefusal: PublishRefusal.optional()
         }), z.object({
           type: z.literal("use-websocket"),
           url: z.string(),
@@ -1811,7 +1843,16 @@ var Api = {
           baseSha: z.string(),
           schemaSha: z.string(),
           sourcesSha: z.string(),
-          commitSha: z.string(),
+          /**
+           * The commit this deployment was built from.
+           *
+           * Optional: a project whose content service is the store of
+           * record has no repository and no commit baked into its build.
+           * The Studio has always parsed this as optional -- see
+           * `useStatus` -- and shows a branch and a commit only when there
+           * is one.
+           */
+          commitSha: z.string().optional(),
           patches: z.array(PatchId),
           /**
            * Of `patches`, the ones that have already SHIPPED.
@@ -1855,7 +1896,8 @@ var Api = {
           deployments: z.array(ValDeployment).optional(),
           config: ValConfig,
           profileId: z.string().nullable(),
-          mode: z.union([z.literal("http"), z.literal("fs")])
+          mode: z.union([z.literal("http"), z.literal("fs")]),
+          publishRefusal: PublishRefusal.optional()
         })])
       })])
     }
@@ -2376,7 +2418,19 @@ var Api = {
         json: GenericError
       }), z.object({
         status: z.literal(409),
-        json: z.union([/** A group that has already shipped. See the 403 above. */
+        json: z.union([
+        /*
+         * This deployment cannot publish this project at all.
+         *
+         * First in the union so it is read before the bare
+         * `{ message }` above it would swallow it. `/stat` carries the
+         * same refusal, so a Studio that is up to date never sends a save
+         * that lands here -- this is for the one that is a poll behind.
+         */
+        z.object({
+          message: z.string(),
+          publishRefusal: PublishRefusal
+        }), /** A group that has already shipped. See the 403 above. */
         z.object({
           message: z.string()
         }), z.object({
@@ -4603,6 +4657,18 @@ function clampDateTimeString(value, options) {
  * validation then reports, rather than wrong ones.
  */
 
+/**
+ * The empty value for a schema — the thing a "create this" affordance writes.
+ *
+ * Returns `JSONValue`, the MUTABLE shape, rather than `Json`. Every value here
+ * is built fresh on the way out — `Object.fromEntries`, a new array, a
+ * primitive — and none of it aliases anything a caller could then mutate out
+ * from under someone. Saying `Json` instead made the type readonly, which is
+ * a claim about sharing that is not true of anything this returns, and left
+ * every caller asserting `as JSONValue` at the point of writing a patch. A
+ * `JSONValue` is still assignable to `Json`, so a reader of the value loses
+ * nothing.
+ */
 function emptyOf(schema, context) {
   if (schema.type === "object") {
     return Object.fromEntries(Object.keys(schema.items).map(function (key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.129.0",
+  "version": "0.133.0",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {
@@ -37,7 +37,7 @@
     "flexsearch": "^0.8.212",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.129.0"
+    "@valbuild/core": "0.130.0"
   },
   "files": [
     "CHANGELOG.md",