@spacefast/common 0.2.2 → 0.4.1

package/dist/contracts/spaces.d.ts

@@ -36,8 +36,8 @@ export declare const SpaceCreateResponseSchema: z.ZodObject<{
             providerMainHostname: z.ZodNullable<z.ZodString>;
             provisioningState: z.ZodEnum<{
                 provisioning: "provisioning";
-                degraded: "degraded";
                 converged: "converged";
+                degraded: "degraded";
             }>;
         }, z.core.$strip>>;
         anonymous: z.ZodBoolean;
@@ -45,10 +45,10 @@ export declare const SpaceCreateResponseSchema: z.ZodObject<{
         title: z.ZodString;
         status: z.ZodEnum<{
             active: "active";
-            failed: "failed";
             provisioning: "provisioning";
             updating: "updating";
             deleting: "deleting";
+            failed: "failed";
         }>;
         disabled: z.ZodNullable<z.ZodObject<{
             at: z.ZodNullable<z.ZodString>;
@@ -160,7 +160,6 @@ export declare const SpaceCreateResponseSchema: z.ZodObject<{
                 burstable: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
-            experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
             inject: z.ZodOptional<z.ZodObject<{
                 head: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -184,6 +183,7 @@ export declare const SpaceCreateResponseSchema: z.ZodObject<{
             remoteUrl: z.ZodNullable<z.ZodString>;
             repository: z.ZodNullable<z.ZodString>;
             defaultBranch: z.ZodNullable<z.ZodString>;
+            provisioned: z.ZodBoolean;
         }, z.core.$strip>>;
         operation: z.ZodNullable<z.ZodObject<{
             id: z.ZodString;
@@ -374,7 +374,6 @@ export declare const spaceCreateSchema: z.ZodDefault<z.ZodOptional<z.ZodObject<{
             burstable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
-        experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
         inject: z.ZodOptional<z.ZodObject<{
             head: z.ZodOptional<z.ZodArray<z.ZodString>>;
             bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -387,7 +386,18 @@ export declare const spaceCreateSchema: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         }, z.core.$strict>>>>;
         defaultDataSource: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-    dataLocation: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodEnum<{
+        team: "team";
+        private: "private";
+        public: "public";
+    }>>;
+    dataLocation: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        auto: "auto";
+        ams: "ams";
+        bur: "bur";
+        dca: "dca";
+        dfw: "dfw";
+    }>>>;
 }, z.core.$strip>>>;
 export declare const spacePatchSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
@@ -460,7 +470,6 @@ export declare const spacePatchSchema: z.ZodObject<{
             burstable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
-        experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
         inject: z.ZodOptional<z.ZodObject<{
             head: z.ZodOptional<z.ZodArray<z.ZodString>>;
             bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -632,8 +641,8 @@ export declare const anonymousClaimStatusResponseSchema: z.ZodObject<{
         expiresAt: z.ZodNullable<z.ZodString>;
         continuation: z.ZodOptional<z.ZodEnum<{
             available: "available";
-            used: "used";
             unavailable: "unavailable";
+            used: "used";
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -789,6 +798,7 @@ export declare const spaceVersionListSchema: z.ZodObject<{
         failedStage: z.ZodNullable<z.ZodString>;
         manifestHash: z.ZodNullable<z.ZodString>;
         buildId: z.ZodNullable<z.ZodString>;
+        gitCommitSha: z.ZodNullable<z.ZodString>;
         importedFromVersionId: z.ZodNullable<z.ZodString>;
         variables: z.ZodNull;
         fileCount: z.ZodNullable<z.ZodNumber>;
@@ -878,7 +888,6 @@ export declare const spaceVersionListSchema: z.ZodObject<{
                 burstable: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
-            experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
             inject: z.ZodOptional<z.ZodObject<{
                 head: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -994,8 +1003,8 @@ export declare const spaceListSchema: z.ZodObject<{
             providerMainHostname: z.ZodNullable<z.ZodString>;
             provisioningState: z.ZodEnum<{
                 provisioning: "provisioning";
-                degraded: "degraded";
                 converged: "converged";
+                degraded: "degraded";
             }>;
         }, z.core.$strip>>;
         anonymous: z.ZodBoolean;
@@ -1003,10 +1012,10 @@ export declare const spaceListSchema: z.ZodObject<{
         title: z.ZodString;
         status: z.ZodEnum<{
             active: "active";
-            failed: "failed";
             provisioning: "provisioning";
             updating: "updating";
             deleting: "deleting";
+            failed: "failed";
         }>;
         disabled: z.ZodNullable<z.ZodObject<{
             at: z.ZodNullable<z.ZodString>;
@@ -1118,7 +1127,6 @@ export declare const spaceListSchema: z.ZodObject<{
                 burstable: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
-            experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
             inject: z.ZodOptional<z.ZodObject<{
                 head: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1142,6 +1150,7 @@ export declare const spaceListSchema: z.ZodObject<{
             remoteUrl: z.ZodNullable<z.ZodString>;
             repository: z.ZodNullable<z.ZodString>;
             defaultBranch: z.ZodNullable<z.ZodString>;
+            provisioned: z.ZodBoolean;
         }, z.core.$strip>>;
         operation: z.ZodNullable<z.ZodObject<{
             id: z.ZodString;
@@ -1195,11 +1204,13 @@ export declare const spaceListSchema: z.ZodObject<{
 export declare const spaceListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
+    principal: z.ZodOptional<z.ZodString>;
     team: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const spaceVersionListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
+    gitCommitSha: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const versionLogEntrySchema: z.ZodObject<{
     timestamp: z.ZodString;
@@ -1658,17 +1669,18 @@ export declare const spaceFilesResponseSchema: z.ZodObject<{
         matched: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const externalVersionFilePathSchema: z.ZodString;
 export declare const spaceVersionFilePathQuerySchema: z.ZodObject<{
     path: z.ZodString;
 }, z.core.$strip>;
 /**
- * Which representation of a path the runtime should hand back: `source` is the
- * uploaded, pre-substitution object; `served` is the immutable byte the
- * version actually serves. A private config input exists in `source` and is
- * absent from `served`.
+ * Which representation of a path the runtime should hand back: `uploaded` is
+ * the byte the publisher uploaded before any transform; `served` is the
+ * immutable byte this version answers with. A private config input exists in
+ * `uploaded` and is absent from `served`.
  */
 export declare const spaceVersionFileViewSchema: z.ZodEnum<{
-    source: "source";
+    uploaded: "uploaded";
     served: "served";
 }>;
 export declare const VERSION_FILE_LINKS_MAX_PATHS = 200;
@@ -1680,7 +1692,7 @@ export declare const VERSION_FILE_LINKS_MAX_PATHS = 200;
 export declare const spaceVersionFileLinksQuerySchema: z.ZodObject<{
     path: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>;
     view: z.ZodDefault<z.ZodEnum<{
-        source: "source";
+        uploaded: "uploaded";
         served: "served";
     }>>;
 }, z.core.$strip>;
@@ -1696,7 +1708,7 @@ export declare const spaceVersionFileLinkSchema: z.ZodObject<{
 export declare const spaceVersionFileLinksResponseSchema: z.ZodObject<{
     versionId: z.ZodString;
     view: z.ZodEnum<{
-        source: "source";
+        uploaded: "uploaded";
         served: "served";
     }>;
     links: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -1704,6 +1716,39 @@ export declare const spaceVersionFileLinksResponseSchema: z.ZodObject<{
         expiresAt: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * Where the preview should land, in the same `landingPath` shape and with the
+ * same normalization as opening a private Space (`POST /v1/spaces/:spaceId/open`).
+ */
+export declare const spaceVersionPreviewSessionCreateSchema: z.ZodObject<{
+    landingPath: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type SpaceVersionPreviewSessionCreate = z.infer<typeof spaceVersionPreviewSessionCreateSchema>;
+/**
+ * A short-lived, version-scoped browsing session for embedding a private
+ * version in the dashboard.
+ *
+ * `url` is the version's own immutable origin with a signed proof on it, and it
+ * is spent on one hop: the runtime verifies the proof, echoes it into an
+ * HttpOnly, partitioned cookie on that origin, and redirects to the same page
+ * without it. The framed document's own location therefore carries no secret —
+ * which matters because it is the customer's page, and every script on it can
+ * read `location.search`. From then on the cookie is what the page and every
+ * relative subresource present. The proof is bound to this one version's host,
+ * so it opens nothing else the Space serves.
+ *
+ * Deliberately not a listable collection: nothing is stored, so there is no
+ * session to enumerate and none to revoke short of moving the Space's session
+ * version. Mint another when this one expires.
+ */
+export declare const spaceVersionPreviewSessionSchema: z.ZodObject<{
+    versionId: z.ZodString;
+    origin: z.ZodString;
+    landingPath: z.ZodString;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type SpaceVersionPreviewSession = z.infer<typeof spaceVersionPreviewSessionSchema>;
 export declare const spaceVersionConventionArtifactKindSchema: z.ZodEnum<{
     headers: "headers";
     redirects: "redirects";
@@ -1967,6 +2012,15 @@ export declare const spaceVersionIntentResponseSchema: z.ZodObject<{
             sha256: z.ZodOptional<z.ZodString>;
             contentType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        bulk: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"zip-cas-v1">;
+            method: z.ZodLiteral<"PUT">;
+            url: z.ZodUnion<[z.ZodString, z.ZodString]>;
+            headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            maxCompressedBytes: z.ZodNumber;
+            maxExpandedBytes: z.ZodNumber;
+            maxBlobs: z.ZodNumber;
+        }, z.core.$strip>>;
         links: z.ZodObject<{
             refresh: z.ZodString;
             resume: z.ZodOptional<z.ZodString>;
@@ -2049,7 +2103,13 @@ export declare const publishRequestSchema: z.ZodObject<{
     space: z.ZodOptional<z.ZodObject<{
         slug: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
-        dataLocation: z.ZodOptional<z.ZodString>;
+        dataLocation: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            auto: "auto";
+            ams: "ams";
+            bur: "bur";
+            dca: "dca";
+            dfw: "dfw";
+        }>>>;
     }, z.core.$strip>>;
     config: z.ZodOptional<z.ZodObject<{
         index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
@@ -2119,7 +2179,6 @@ export declare const publishRequestSchema: z.ZodObject<{
             burstable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         markdownNegotiation: z.ZodOptional<z.ZodBoolean>;
-        experimental_gutenberg: z.ZodOptional<z.ZodBoolean>;
         inject: z.ZodOptional<z.ZodObject<{
             head: z.ZodOptional<z.ZodArray<z.ZodString>>;
             bodyStart: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -2132,6 +2191,11 @@ export declare const publishRequestSchema: z.ZodObject<{
         }, z.core.$strict>>>>;
         defaultDataSource: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    access: z.ZodOptional<z.ZodEnum<{
+        team: "team";
+        private: "private";
+        public: "public";
+    }>>;
     deletePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
     immutableAssetPrefixes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     spaceId: z.ZodOptional<z.ZodString>;
@@ -2180,6 +2244,15 @@ export declare const publishUploadReceiptSchema: z.ZodObject<{
         sha256: z.ZodOptional<z.ZodString>;
         contentType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    bulk: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"zip-cas-v1">;
+        method: z.ZodLiteral<"PUT">;
+        url: z.ZodUnion<[z.ZodString, z.ZodString]>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        maxCompressedBytes: z.ZodNumber;
+        maxExpandedBytes: z.ZodNumber;
+        maxBlobs: z.ZodNumber;
+    }, z.core.$strip>>;
     links: z.ZodObject<{
         refresh: z.ZodString;
         resume: z.ZodOptional<z.ZodString>;
@@ -2269,6 +2342,9 @@ export declare const publishActivationSchema: z.ZodObject<{
         superseded: "superseded";
     }>;
     currentLiveVersionId: z.ZodNullable<z.ZodString>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        channel_promotion_manual: "channel_promotion_manual";
+    }>>;
 }, z.core.$strip>;
 export declare const publishNextSchema: z.ZodObject<{
     action: z.ZodEnum<{
@@ -2327,6 +2403,9 @@ export declare const publishReceiptSchema: z.ZodObject<{
             superseded: "superseded";
         }>;
         currentLiveVersionId: z.ZodNullable<z.ZodString>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            channel_promotion_manual: "channel_promotion_manual";
+        }>>;
     }, z.core.$strip>;
     next: z.ZodObject<{
         action: z.ZodEnum<{
@@ -2347,14 +2426,15 @@ export declare const publishReceiptSchema: z.ZodObject<{
         remoteUrl: z.ZodNullable<z.ZodString>;
         repository: z.ZodNullable<z.ZodString>;
         defaultBranch: z.ZodNullable<z.ZodString>;
+        provisioned: z.ZodBoolean;
     }, z.core.$strip>>;
     authMode: z.ZodOptional<z.ZodEnum<{
         anonymous: "anonymous";
         authenticated: "authenticated";
     }>>;
     persistence: z.ZodOptional<z.ZodEnum<{
-        managed: "managed";
         temporary: "temporary";
+        managed: "managed";
     }>>;
     operation: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
@@ -2426,6 +2506,15 @@ export declare const publishReceiptSchema: z.ZodObject<{
             sha256: z.ZodOptional<z.ZodString>;
             contentType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        bulk: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"zip-cas-v1">;
+            method: z.ZodLiteral<"PUT">;
+            url: z.ZodUnion<[z.ZodString, z.ZodString]>;
+            headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            maxCompressedBytes: z.ZodNumber;
+            maxExpandedBytes: z.ZodNumber;
+            maxBlobs: z.ZodNumber;
+        }, z.core.$strip>>;
         links: z.ZodObject<{
             refresh: z.ZodString;
             resume: z.ZodOptional<z.ZodString>;
@@ -2529,6 +2618,15 @@ export declare const spaceVersionRefreshResponseSchema: z.ZodObject<{
             sha256: z.ZodOptional<z.ZodString>;
             contentType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        bulk: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"zip-cas-v1">;
+            method: z.ZodLiteral<"PUT">;
+            url: z.ZodUnion<[z.ZodString, z.ZodString]>;
+            headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            maxCompressedBytes: z.ZodNumber;
+            maxExpandedBytes: z.ZodNumber;
+            maxBlobs: z.ZodNumber;
+        }, z.core.$strip>>;
         links: z.ZodObject<{
             refresh: z.ZodString;
             resume: z.ZodOptional<z.ZodString>;
@@ -2602,10 +2700,10 @@ export declare const spaceRuntimeStatusSchema: z.ZodObject<{
     liveUrl: z.ZodNullable<z.ZodString>;
     runtimeState: z.ZodEnum<{
         active: "active";
-        failed: "failed";
         provisioning: "provisioning";
         updating: "updating";
         deleting: "deleting";
+        failed: "failed";
     }>;
     liveVersionStatus: z.ZodNullable<z.ZodEnum<{
         failed: "failed";
@@ -2714,8 +2812,11 @@ export declare const spaceRuntimeStatusSchema: z.ZodObject<{
             tables: z.ZodDefault<z.ZodArray<z.ZodString>>;
             queries: z.ZodDefault<z.ZodArray<z.ZodString>>;
             mutations: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
             endpoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    read: "read";
+                    write: "write";
+                }>;
                 method: z.ZodEnum<{
                     POST: "POST";
                     PUT: "PUT";
@@ -2785,6 +2886,8 @@ export declare const spaceRuntimeStatusSchema: z.ZodObject<{
                 spam: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
                 email: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
                 content: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+                storage: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+                connectors: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
             }, z.core.$strip>>;
             executionState: z.ZodEnum<{
                 ready: "ready";
@@ -2841,8 +2944,11 @@ export declare const spaceRuntimeStatusSchema: z.ZodObject<{
             tables: z.ZodDefault<z.ZodArray<z.ZodString>>;
             queries: z.ZodDefault<z.ZodArray<z.ZodString>>;
             mutations: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
             endpoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                mode: z.ZodEnum<{
+                    read: "read";
+                    write: "write";
+                }>;
                 method: z.ZodEnum<{
                     POST: "POST";
                     PUT: "PUT";
@@ -2912,6 +3018,8 @@ export declare const spaceRuntimeStatusSchema: z.ZodObject<{
                 spam: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
                 email: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
                 content: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+                storage: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+                connectors: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
             }, z.core.$strip>>;
             executionState: z.ZodEnum<{
                 ready: "ready";

package/dist/contracts/spaces.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { SPACE_SLUG_MAX_LENGTH } from "../slug-policy/index.js";
 import { normalizeVersionPath } from "../utils/version-path.js";
-import { accessRoleSchema, publishedAccessSchema } from "./access.js";
+import { accessRoleSchema, accessScopePathSchema, publishedAccessSchema, spaceAccessPresetSchema, } from "./access.js";
 import { AsyncOperationSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, } from "./common.js";
+import { dataLocationSchema } from "./data-location.js";
 import { versionStatus, spaceStatus } from "./enums.js";
 import { runtimeInternalArtifactPath } from "./execution.js";
 import { uploadInstructionsSchema, manifestFileSchema } from "./internal.js";
@@ -66,7 +67,10 @@ export const spaceCreateSchema = z
     slug: z.string().min(2).max(55).optional(),
     title: z.string().min(1).max(255).optional(),
     config: spaceConfigSchema.optional().describe("Initial SpaceConfig overlay for the new space."),
-    dataLocation: z.string().min(1).optional(),
+    access: spaceAccessPresetSchema
+        .optional()
+        .describe("Set the initial root access for this new team-owned Space. Omit this field to use the team's default."),
+    dataLocation: dataLocationSchema.optional(),
 })
     .superRefine((value, ctx) => {
     if (value.teamId && value.principal?.type === "team" && value.teamId !== value.principal.id) {
@@ -321,13 +325,22 @@ export const spaceListSchema = z.object({
     pagination: CursorPaginationSchema,
 });
 export const spaceListQuerySchema = cursorListQuerySchema.extend({
+    principal: principalIdSchema
+        .optional()
+        .describe("Filter that limits results to spaces owned by this external principal."),
     team: z
         .string()
         .min(1)
         .optional()
         .describe("Filter that limits results to spaces owned by this team id or slug."),
 });
-export const spaceVersionListQuerySchema = cursorListQuerySchema;
+export const spaceVersionListQuerySchema = cursorListQuerySchema.extend({
+    gitCommitSha: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/, "gitCommitSha must be a full lowercase commit SHA.")
+        .optional()
+        .describe("Only versions built from this exact git commit."),
+});
 // Version processing log lines (upload/finalize/promote output), newest-first.
 export const versionLogEntrySchema = z.object({
     timestamp: z.string().datetime().describe("Instant when the version last changed state."),
@@ -392,7 +405,7 @@ export const spaceFilesResponseSchema = z.object({
     index: spaceVersionFileIndexSchema,
     search: spaceVersionFilesSearchSchema,
 });
-const externalVersionFilePathSchema = z
+export const externalVersionFilePathSchema = z
     .string()
     .min(1)
     .refine((value) => {
@@ -409,12 +422,12 @@ export const spaceVersionFilePathQuerySchema = z.object({
     path: externalVersionFilePathSchema,
 });
 /**
- * Which representation of a path the runtime should hand back: `source` is the
- * uploaded, pre-substitution object; `served` is the immutable byte the
- * version actually serves. A private config input exists in `source` and is
- * absent from `served`.
+ * Which representation of a path the runtime should hand back: `uploaded` is
+ * the byte the publisher uploaded before any transform; `served` is the
+ * immutable byte this version answers with. A private config input exists in
+ * `uploaded` and is absent from `served`.
  */
-export const spaceVersionFileViewSchema = z.enum(["source", "served"]);
+export const spaceVersionFileViewSchema = z.enum(["uploaded", "served"]);
 // Minting is a read, so it rides the URL, which has a practical ceiling a JSON
 // body does not. Clients chunk; each chunk is one authorization.
 export const VERSION_FILE_LINKS_MAX_PATHS = 200;
@@ -432,8 +445,8 @@ export const spaceVersionFileLinksQuerySchema = z.object({
         .preprocess((value) => (typeof value === "string" ? [value] : value), z.array(spaceVersionFileLinkPathSchema).min(1).max(VERSION_FILE_LINKS_MAX_PATHS))
         .describe("Version-relative file paths to mint read links for; repeat the parameter per path."),
     view: spaceVersionFileViewSchema
-        .default("source")
-        .describe("Which representation to read: the uploaded source or the served byte."),
+        .default("uploaded")
+        .describe("Which representation to read: `uploaded` is the byte the publisher uploaded before any transform; `served` is the immutable byte this version answers with."),
 });
 export const spaceVersionFileLinkSchema = z.object({
     url: z.string().url().describe("Short-lived signed URL that serves the file's bytes."),
@@ -449,6 +462,43 @@ export const spaceVersionFileLinksResponseSchema = z.object({
     view: spaceVersionFileViewSchema,
     links: z.record(z.string(), spaceVersionFileLinkSchema),
 });
+/**
+ * Where the preview should land, in the same `landingPath` shape and with the
+ * same normalization as opening a private Space (`POST /v1/spaces/:spaceId/open`).
+ */
+export const spaceVersionPreviewSessionCreateSchema = z.object({
+    landingPath: accessScopePathSchema
+        .default("/")
+        .describe("Page to open in the preview. Defaults to the version's root."),
+});
+/**
+ * A short-lived, version-scoped browsing session for embedding a private
+ * version in the dashboard.
+ *
+ * `url` is the version's own immutable origin with a signed proof on it, and it
+ * is spent on one hop: the runtime verifies the proof, echoes it into an
+ * HttpOnly, partitioned cookie on that origin, and redirects to the same page
+ * without it. The framed document's own location therefore carries no secret —
+ * which matters because it is the customer's page, and every script on it can
+ * read `location.search`. From then on the cookie is what the page and every
+ * relative subresource present. The proof is bound to this one version's host,
+ * so it opens nothing else the Space serves.
+ *
+ * Deliberately not a listable collection: nothing is stored, so there is no
+ * session to enumerate and none to revoke short of moving the Space's session
+ * version. Mint another when this one expires.
+ */
+export const spaceVersionPreviewSessionSchema = z.object({
+    versionId: z.string(),
+    /** The version origin the preview is scoped to; nothing outside it is authorized. */
+    origin: z.string().url(),
+    landingPath: z.string(),
+    url: z
+        .string()
+        .url()
+        .describe("Frame this URL. Following it once exchanges the proof it carries for a cookie and redirects to the same page without it."),
+    expiresAt: z.string().datetime().describe("When the preview session stops working."),
+});
 export const spaceVersionConventionArtifactKindSchema = z.enum(["redirects", "headers"]);
 export const spaceVersionConventionArtifactPathSchema = z.enum(["_redirects", "_headers"]);
 export const spaceVersionConventionArtifactSourceSchema = z.enum([
@@ -586,12 +636,22 @@ export const publishRequestSchema = z
         .object({
         slug: z.string().min(2).max(55).optional(),
         title: z.string().min(1).max(255).optional(),
-        dataLocation: z.string().min(1).optional(),
+        dataLocation: dataLocationSchema.optional(),
     })
         .optional(),
     config: spaceConfigSchema.optional().describe("SpaceConfig overlay to store on the space."),
+    access: spaceAccessPresetSchema
+        .optional()
+        .describe("Set the initial root access for this new team-owned Space. Omit this field to use the team's default. Do not set this field with spaceId."),
 })
     .superRefine((value, ctx) => {
+    if (value.access !== undefined && value.spaceId !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "access applies only when this publish creates a Space.",
+            path: ["access"],
+        });
+    }
     if (value.teamId && value.principal?.type === "team" && value.teamId !== value.principal.id) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -654,11 +714,15 @@ export const publishActivationSchema = z.object({
         .describe("Channel this publish targeted; null means a ready version without promotion."),
     outcome: z
         .enum(["activated", "unpromoted", "superseded", "pending"])
-        .describe("activated: the live pointer moved to this version. unpromoted: ready with channel null, by request. superseded: ready, but a newer publish holds the live pointer. pending: not settled yet."),
+        .describe("activated: the live pointer moved to this version. unpromoted: ready without promotion — either the caller passed channel null, or the live channel's promotion policy held it; `reason` says which. superseded: ready, but a newer publish holds the live pointer. pending: not settled yet."),
     currentLiveVersionId: z
         .string()
         .nullable()
         .describe("The version currently serving live traffic, or null when the space has none."),
+    reason: z
+        .enum(["channel_promotion_manual"])
+        .optional()
+        .describe("Why the outcome is not what the caller asked for. channel_promotion_manual: the live channel's promotion policy is manual, so this publish finalized ready but unpromoted; POST promote to move the pointer."),
 });
 // A deterministic projection of (version status, activation outcome, pending
 // bytes, operation state). An agent drives the whole lifecycle by branching on