@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/spaces.js

@@ -1,17 +1,19 @@
 import { z } from "zod";
 import { SPACE_SLUG_MAX_LENGTH } from "../slug-policy/index.js";
 import { normalizeVersionPath } from "../utils/version-path.js";
-import { publishedAccessSchema } from "./access.js";
+import { accessRoleSchema, publishedAccessSchema } from "./access.js";
 import { AsyncOperationSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, } from "./common.js";
 import { versionStatus, spaceStatus } from "./enums.js";
-import { conventionFilesSchema, uploadInstructionsSchema, manifestFileSchema, uploadManifestFileSchema, } from "./internal.js";
-import { VersionSchema, PublishSourceSchema, SpaceSchema, spaceSettingsDigestSchema, } from "./resources.js";
+import { runtimeInternalArtifactPath } from "./execution.js";
+import { uploadInstructionsSchema, manifestFileSchema } from "./internal.js";
+import { VersionSchema, PublishSourceSchema, SpaceSchema, spaceGitSchema, spaceSettingsDigestSchema, } from "./resources.js";
 import { runtimeAppSchema } from "./runtime-app.js";
 import { SPACE_CONFIG_ACCEPTED_FILES, spaceConfigSchema, spacePlacementConfigSchema, } from "./space-config.js";
 import { principalIdSchema } from "./transfers.js";
-// Capacity accounting for the provider site a space runs on. A space IS a
-// site, so occupancy is not a question — storage is. Warm-pool inventory rows
-// carry the same shape before a space adopts them.
+export const VERSION_BUILD_LOG_MAX_LENGTH = 512 * 1024;
+// Capacity accounting for the provider site a space runs on. A space IS a site,
+// so the only question is storage, not occupancy. Warm-pool inventory rows carry
+// the same shape before a space adopts them.
 export const SpaceCapacitySchema = z
     .object({
     storageBytes: z
@@ -22,31 +24,6 @@ export const SpaceCapacitySchema = z
         .describe("Storage budget for the space in bytes."),
 })
     .describe("Capacity accounting for a space's provider site.");
-export const SpacePressureSchema = z
-    .object({
-    ewmaLimitedPct: z.number().nonnegative().optional(),
-    ewma429: z.number().nonnegative().optional(),
-    ewma429PerMin: z.number().nonnegative().optional(),
-    ewmaWorkersMax: z.number().nonnegative().optional(),
-    ewmaCpuPct: z.number().nonnegative().optional(),
-    lastSampleAt: z.string().datetime().optional(),
-    consecutivePressured: z.number().int().nonnegative().optional(),
-    consecutiveClean: z.number().int().nonnegative().optional(),
-    // Monotonic CAS token shared by explicit operator hold actions and the
-    // pressure sampler. Every durable hold transition advances it, including
-    // transitions that restore a prior timestamp.
-    placementHoldRevision: z.number().int().nonnegative().optional(),
-    // Provenance stamp for the sampler's automatic hold: set on trip to the
-    // exact hold instant it wrote, so release only clears holds the pressure
-    // pipeline itself set — never an operator-set placement hold.
-    pressureHoldUntil: z.string().datetime().optional(),
-    // Last time a bulk-lane engine job on this space reported activity via the
-    // job callbacks (runtime/callback-events.ts); the sampler discounts the
-    // CPU signal while this is within the sampling window.
-    lastBulkLaneActivityAt: z.string().datetime().optional(),
-})
-    .passthrough()
-    .describe("Placement pressure signals computed outside the request path.");
 export const spaceClaimReceiptSchema = z.object({
     key: z
         .string()
@@ -55,7 +32,7 @@ export const spaceClaimReceiptSchema = z.object({
     url: z
         .string()
         .url()
-        .describe("The site door: the live URL with the space key in /__/<key> form. Opening it exchanges the key for a private view session and lands on the site. Same key, URL form — share it as carefully as the key."),
+        .describe("The site door: the live URL with the space key in /__/<key> form. Opening it exchanges the key for a private view session and lands on the site. It is the same key in URL form, so share it as carefully as the key."),
     claimUrl: z
         .string()
         .url()
@@ -67,16 +44,16 @@ export const SpaceCreateResponseSchema = z.object({
     access: publishedAccessSchema,
     claim: spaceClaimReceiptSchema.optional(),
 });
-// Stored per-version diagnostic surfaced on the space diagnostics feed: the shared
-// Diagnostic shape (contracts/common.ts) plus persistence identity.
+// The shared Diagnostic shape (contracts/common.ts) plus persistence identity.
 export const spaceDiagnosticSchema = baseDiagnosticSchema.extend({
     id: z.string().describe("Stable diagnostic record id."),
     versionId: z.string().describe("Version the diagnostic was recorded against."),
     createdAt: z.string().datetime(),
 });
+// The current diagnostic set for a space, returned whole: the route takes no
+// query at all, so there is no cursor to advertise.
 export const spaceDiagnosticListResponseSchema = z.object({
     data: z.array(spaceDiagnosticSchema),
-    pagination: CursorPaginationSchema,
 });
 export const principalRefInputSchema = z.object({
     type: z.enum(["team", "external"]).describe("Owning principal kind."),
@@ -128,6 +105,10 @@ export const spacePatchSchema = z
         .boolean()
         .optional()
         .describe("Hide the live production site from search engines. This applies only to live hostnames of claimed spaces. Preview and version hostnames are always noindex."),
+    pinned: z
+        .boolean()
+        .optional()
+        .describe("Pin the space to the top of its team's space list, for everyone on the team. This is presentation only: it never changes what the space serves."),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -146,10 +127,8 @@ export const spacePatchSchema = z
         });
     }
 });
-// The one claim endpoint (POST /v1/claim). A converging loop: the caller sends
-// what it has decided so far; the server either commits the claim or answers
-// with the single decision still missing (`login_required`, `team_required`,
-// `consent_required`).
+// POST /v1/claim returns the one missing decision or commits the claim. The
+// caller repeats the request with each completed decision.
 export const anonymousClaimSchema = z.object({
     key: z
         .string()
@@ -184,7 +163,9 @@ export const anonymousClaimSharingSummarySchema = z.object({
         status: z.enum(["pending", "accepted"]),
         grants: z.array(z.object({
             scope: z.string().startsWith("/"),
-            role: z.enum(["viewer", "commenter", "editor"]),
+            // The person's Grant carries a full access role; narrowing it here
+            // used to make a `manager` share unrepresentable in a claim preview.
+            role: accessRoleSchema,
         })),
     })),
     links: z.array(z.object({
@@ -282,9 +263,8 @@ export const spaceClaimReminderSchema = z.object({
 export const spaceClaimReminderResponseSchema = z.object({
     accepted: z.literal(true),
 });
-// Shared by spaceVersionCreateSchema and publishRequestSchema: both accept the
-// same manifest-mutation fields and enforce the same "requires a declared
-// files manifest / snapshot mode" rules on them.
+// Shared by spaceVersionCreateSchema and publishRequestSchema, which enforce
+// the same snapshot-mode rules on these fields.
 const manifestMutationFieldsSchema = {
     deletePaths: z
         .array(z.string().min(1))
@@ -319,19 +299,16 @@ export const spaceVersionCreateSchema = z
         .describe("Additional control-plane-only provenance for build and deploy read models."),
     buildLog: z
         .string()
-        .max(64_000)
+        .max(VERSION_BUILD_LOG_MAX_LENGTH)
         .optional()
         .describe("Build transcript truncated to a bounded size for deploys that ran a local build before publishing."),
-    conventionFiles: conventionFilesSchema
-        .optional()
-        .describe("Routing convention contents used when deciding whether this publish is unchanged. The same values are supplied again when the version is finalized."),
     finalize: z
         .object({ channel: z.literal("live").nullable().optional() })
         .optional()
         .describe("Finalize intent for a declared upload. When every declared file lands, the version finalizes itself; the explicit finalize call remains available for recovery and replay."),
     files: z
-        .array(uploadManifestFileSchema)
-        .describe("The complete desired file manifest. Local-byte entries require `sha256` and are uploaded to a content-addressed target. A `sourceUrl` entry may omit `sha256` because the runtime computes it while fetching. Hashes also let updates skip unchanged files."),
+        .array(manifestFileSchema)
+        .describe("The complete desired file manifest. `sha256` is optional: omit it to upload by path and let the runtime hash the bytes, or include it to upload by content address, with the digest verified as the bytes land. A `sourceUrl` entry is fetched and hashed by the runtime."),
     ...manifestMutationFieldsSchema,
 })
     .superRefine(refineManifestMutationRules);
@@ -358,10 +335,10 @@ export const versionLogEntrySchema = z.object({
     code: z.string().describe("Stable version.{status} code for the line."),
     message: z.string().describe("Human-readable log line."),
 });
-export const VERSION_BUILD_LOG_MAX_LENGTH = 512 * 1024;
+// A version's log is a bounded record `limit` truncates; it never pages, so it
+// declares no cursor.
 export const versionLogListResponseSchema = z.object({
     data: z.array(versionLogEntrySchema),
-    pagination: CursorPaginationSchema,
 });
 export const spaceVersionGeneratedPreviewSchema = z.object({
     kind: z.literal("image"),
@@ -415,8 +392,21 @@ export const spaceFilesResponseSchema = z.object({
     index: spaceVersionFileIndexSchema,
     search: spaceVersionFilesSearchSchema,
 });
+const externalVersionFilePathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    try {
+        return !runtimeInternalArtifactPath(normalizeVersionPath(value));
+    }
+    catch {
+        return false;
+    }
+}, {
+    message: "Path must be version-relative and cannot address runtime-internal artifacts.",
+});
 export const spaceVersionFilePathQuerySchema = z.object({
-    path: z.string().min(1),
+    path: externalVersionFilePathSchema,
 });
 /**
  * Which representation of a path the runtime should hand back: `source` is the
@@ -425,28 +415,17 @@ export const spaceVersionFilePathQuerySchema = z.object({
  * absent from `served`.
  */
 export const spaceVersionFileViewSchema = z.enum(["source", "served"]);
-// Minting is a read, so it rides the URL — and a URL has a practical ceiling
-// that a JSON body does not. Clients chunk; each chunk is one authorization.
+// 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;
 // Structural admission only. Whether the version HOLDS a path is the runtime's
-// answer, given when the link is followed — the control plane keeps no catalog
-// to check against and does not round-trip per path to fake one.
-const spaceVersionFileLinkPathSchema = z
-    .string()
-    .min(1)
-    .refine((value) => {
-    try {
-        normalizeVersionPath(value);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}, { message: "Path must be version-relative, without traversal or control characters." });
+// answer, given when the link is followed; the control plane keeps no catalog
+// to check against.
+const spaceVersionFileLinkPathSchema = externalVersionFilePathSchema;
 /**
- * Repeated `path` query parameters — `?path=index.html&path=about.html`. One
- * path arrives as a bare string, so it is lifted into the batch shape before
- * the per-path rules run.
+ * Repeated `path` query parameters, for example
+ * `?path=index.html&path=about.html`. One path arrives as a bare string, so it
+ * is lifted into the batch shape before the per-path rules run.
  */
 export const spaceVersionFileLinksQuerySchema = z.object({
     path: z
@@ -461,7 +440,7 @@ export const spaceVersionFileLinkSchema = z.object({
     expiresAt: z.string().describe("When the link stops working."),
 });
 /**
- * Minting is blind to path validity — the control plane authorizes the version,
+ * Minting is blind to path validity. The control plane authorizes the version,
  * not the path. A path that is not in the selected catalog view answers
  * `version_file_not_found` when the link is followed.
  */
@@ -496,8 +475,12 @@ export const spaceVersionConventionArtifactsResponseSchema = z.object({
     artifacts: z.array(spaceVersionConventionArtifactMetadataSchema),
 });
 export const spaceVersionConventionArtifactQuerySchema = z.object({
-    kind: spaceVersionConventionArtifactKindSchema.optional(),
-    path: spaceVersionConventionArtifactPathSchema.optional(),
+    kind: spaceVersionConventionArtifactKindSchema
+        .optional()
+        .describe("Which artifact to read, named by kind. Pass this or `path`."),
+    path: spaceVersionConventionArtifactPathSchema
+        .optional()
+        .describe("Which artifact to read, named by its source path. Pass this or `kind`."),
 });
 export const spaceVersionConventionArtifactContentResponseSchema = spaceVersionConventionArtifactMetadataSchema.extend({
     encoding: z.enum(["utf8", "base64"]),
@@ -505,11 +488,10 @@ export const spaceVersionConventionArtifactContentResponseSchema = spaceVersionC
     truncated: z.boolean(),
 });
 /**
- * Where a routing diagnostic came from — a committed path in the version the
- * publisher can open. Wider than the convention artifacts: the Spacefast config
- * file states routing rules too, and they compile through the same compiler and
- * report the same codes. Every accepted config filename is listed because
- * finalize reads whichever one the version ships, and naming the canonical
+ * Where a routing diagnostic came from: a committed path in the version the
+ * publisher can open. Wider than the convention artifacts, because the config
+ * file states routing rules too. Every accepted config filename is listed
+ * because finalize reads whichever one the version ships, and naming
  * `sf.jsonc` at a version that committed `spacefast.jsonc` sends the publisher
  * to a file that is not there.
  */
@@ -525,14 +507,23 @@ export const spaceVersionRoutingDiagnosticSchema = z.object({
     code: z.string(),
     message: z.string(),
     source: z.string(),
+    deferredUntilSubstitution: z.literal(true).optional(),
+});
+export const spaceRoutingComputeSchema = z.object({
+    latestVersionId: z.string().nullable(),
+    redirects: z.string().nullable(),
+    headers: z.string().nullable(),
+    diagnostics: z.array(spaceVersionRoutingDiagnosticSchema),
+    variableDependencies: z.array(z.string()),
+    systemVariableDependencies: z.array(z.string()),
 });
 export const spaceVersionComputedRoutingSummarySchema = z.object({
     versionId: z.string(),
     source: z.object({
         artifacts: z.array(spaceVersionConventionArtifactMetadataSchema),
     }),
-    // Finalize-written scalars, not a replay of a stored compiled-routing blob:
-    // the runtime owns the compile and reports these counts on its receipt.
+    // Finalize-written scalars: the runtime owns the compile and reports these
+    // counts on its receipt.
     compiled: z.object({
         redirectRuleCount: z.number().int().nonnegative(),
         headerRuleCount: z.number().int().nonnegative(),
@@ -540,9 +531,8 @@ export const spaceVersionComputedRoutingSummarySchema = z.object({
     }),
     diagnostics: z.array(spaceVersionRoutingDiagnosticSchema),
 });
-// Upload state is inferable (internal-docs/platform.md L2216): `upload` present means bytes are
-// still needed (then finalize); `versionId` null means the manifest matched and nothing changed.
-// No redundant booleans ride along.
+// `upload` present means bytes are still needed, then finalize. `versionId`
+// null means the manifest matched and nothing changed.
 export const spaceVersionIntentResponseSchema = z.object({
     versionId: z
         .string()
@@ -562,20 +552,19 @@ export const publishRequestSchema = z
     teamId: z.string().nullable().optional(),
     principal: principalRefInputSchema.optional(),
     files: z
-        .array(uploadManifestFileSchema)
-        .describe("Desired file manifest for a declared publish session. Local-byte entries require `sha256`; sourceUrl entries may omit it. Clients upload returned targets, then finalize."),
+        .array(manifestFileSchema)
+        .describe("Desired file manifest for a declared publish session. `sha256` is optional: omitted local bytes receive path-addressed upload targets and are hashed by the runtime; declared hashes receive content-addressed targets and can reuse existing bytes. Clients upload returned targets, then finalize."),
     ...manifestMutationFieldsSchema,
     source: PublishSourceSchema.optional().describe('Publish provenance recorded on the version; defaults to {kind: "direct_upload"}.'),
-    // Same fields, same bounds as spaceVersionCreateSchema: a publish that ran
-    // a build carries its transcript and provenance whichever door it enters
-    // by, so the first version of a space is not poorer than its second.
+    // Same fields and bounds as spaceVersionCreateSchema, so a publish that ran
+    // a build carries its transcript whichever door it enters by.
     sourceMetadata: z
         .record(z.string(), z.unknown())
         .optional()
         .describe("Additional control-plane-only provenance for build/deploy read models."),
     buildLog: z
         .string()
-        .max(64_000)
+        .max(VERSION_BUILD_LOG_MAX_LENGTH)
         .optional()
         .describe("Bounded build transcript for deploys that ran a local build before publishing."),
     publishMode: z
@@ -618,21 +607,46 @@ export const publishUploadReceiptSchema = z.object({
 export const publishReceiptSpaceSchema = z.object({
     id: z.string(),
     slug: z.string(),
+    title: z.string(),
     publicName: z.string(),
-    defaultHostname: z.string(),
+    // The server always names the managed hostname it allocated. A receipt
+    // rendered by a client (`sf publish --json`) can only report what the API told
+    // it, so this is absent rather than guessed: the apex is environment-resolved
+    // (see config/domains.ts `resolveViewFastApex`) and a client that invents
+    // `<slug>.view.fast` would hand a caller a production address that, off
+    // production, belongs to nothing.
+    defaultHostname: z.string().optional(),
     liveUrl: z.string().nullable(),
 });
+/**
+ * The claim block as it rides on a publish receipt. Same members as the
+ * server's {@link spaceClaimReceiptSchema}, with the URL formats relaxed to
+ * plain strings so a client-rendered receipt can mask the three key-bearing
+ * members (`key`, `url`, `claimUrl`) with {@link REDACTED_RECEIPT_SECRET} while
+ * keeping the block's shape stable. `expiresAt` is never masked: it is what
+ * tells an agent the space is temporary and by when it has to be claimed.
+ */
+export const publishReceiptClaimSchema = spaceClaimReceiptSchema.extend({
+    key: z.string().min(1),
+    url: z.string().min(1),
+    claimUrl: z.string().min(1),
+});
+/** The stand-in a surface writes where a secret would otherwise be printed. */
+export const REDACTED_RECEIPT_SECRET = "[REDACTED]";
 export const publishReceiptVersionSchema = z.object({
     id: z.string(),
     status: VersionSchema.shape.status,
-    immutableUrl: z.string(),
+    immutableUrl: z
+        .string()
+        .nullable()
+        .describe("Permanent version URL, or null while the version is still being finalized."),
     ref: z.string().nullable().optional(),
     number: z.number().int().positive().nullable().optional(),
     manifestHash: z.string().nullable(),
 });
-// Liveness is never a version status — it is the channel pointer, reported
-// here. "Ready and live" (activated), "ready but outraced" (superseded), and
-// "ready by design" (unpromoted) are three different receipts.
+// Liveness is the channel pointer, never a version status: "ready and live"
+// (activated), "ready but outraced" (superseded), and "ready by design"
+// (unpromoted) are three different receipts.
 export const publishActivationSchema = z.object({
     channel: z
         .enum(["live"])
@@ -646,9 +660,9 @@ export const publishActivationSchema = z.object({
         .nullable()
         .describe("The version currently serving live traffic, or null when the space has none."),
 });
-// The receipt's normative next step: the deterministic projection of
-// (version status, activation outcome, pending bytes, operation state). An
-// agent drives the whole lifecycle by branching on `action` alone.
+// A deterministic projection of (version status, activation outcome, pending
+// bytes, operation state). An agent drives the whole lifecycle by branching on
+// `action` alone.
 export const publishNextSchema = z.object({
     action: z
         .enum(["done", "upload", "finalize", "poll"])
@@ -670,19 +684,49 @@ export const publishReceiptSchema = z.object({
     version: publishReceiptVersionSchema,
     activation: publishActivationSchema,
     next: publishNextSchema,
+    // The other way to publish this same space. Present on every receipt that
+    // could resolve it, so an agent that just published once already knows how to
+    // deploy the next change from a checkout — and so an anonymous publisher
+    // learns that the key it is already holding is also its git password. Absent
+    // rather than guessed when the space has no repository yet.
+    git: spaceGitSchema
+        .optional()
+        .describe('Git remote for this space. `managedBy: "spacefast"` carries a `remoteUrl` you can push to; `managedBy: "github"` means the space deploys from GitHub and direct pushes are refused.'),
+    // How the publish was authorized, and what that means for the space's
+    // lifetime. An anonymous space is temporary: it expires at `claim.expiresAt`
+    // unless somebody claims it. An agent branches on these two rather than
+    // inferring temporariness from the presence of a claim block it may not be
+    // allowed to see. Optional because the API derives ownership from the
+    // credential and does not restate it; the CLI and MCP always set them.
+    authMode: z
+        .enum(["anonymous", "authenticated"])
+        .optional()
+        .describe("anonymous: authorized by a space key. authenticated: authorized by an account."),
+    persistence: z
+        .enum(["temporary", "managed"])
+        .optional()
+        .describe("temporary: the space expires unless claimed. managed: the space belongs to a team and persists."),
     operation: AsyncOperationSchema.optional().describe("Background finalize operation when publish work continues asynchronously."),
     upload: publishUploadReceiptSchema.optional(),
-    claim: spaceClaimReceiptSchema.optional(),
+    claim: publishReceiptClaimSchema.optional(),
     diagnostics: z
         .array(baseDiagnosticSchema)
         .optional()
         .describe("Publish diagnostics. Includes the `noop_publish` info diagnostic when nothing changed (the only noop signal), manifest warnings such as `path_case_collision`, and serving-shape notes such as `single_html_index` or `files_mode_inferred`."),
     links: z
         .object({
+        refresh: z
+            .string()
+            .optional()
+            .describe("Upload-instruction refresh endpoint; present while bytes still need uploading."),
+        // Transition alias for clients baked before the rename (#2449): same value
+        // as `refresh`, emitted so a deployed client that reads `links.resume`
+        // still finds a working URL. Remove with the rest of the alias once every
+        // baked client is rebuilt.
         resume: z
             .string()
             .optional()
-            .describe("Resume endpoint; present while bytes still need uploading."),
+            .describe("Deprecated alias for `refresh`; carries the identical URL."),
         finalize: z
             .string()
             .optional()
@@ -702,9 +746,9 @@ export const publishReceiptSchema = z.object({
         .optional()
         .describe("Follow-up links so agents can act on the receipt without knowing the full API."),
 });
-// Same inferable contract as the intent response: `upload` present means bytes are still
-// needed (then finalize); absent means everything declared has already landed.
-export const spaceVersionResumeResponseSchema = z.object({
+// Same contract as the intent response: `upload` present means bytes are still
+// needed, then finalize; absent means everything declared has landed.
+export const spaceVersionRefreshResponseSchema = z.object({
     versionId: z.string(),
     upload: uploadInstructionsSchema
         .nullable()
@@ -714,10 +758,9 @@ export const spaceVersionResumeResponseSchema = z.object({
         .default([])
         .describe("Manifest paths ignored by the server because the current plan does not allow them."),
 });
-// Promote body (spec "Explicit version routes"): `{ channel? }` defaulting to
-// "live". Channels beyond live arrive additively; non-live names reject with
-// `channel_unsupported` until then. Rollback is promoting an older ready
-// version to the same channel.
+// `{ channel? }` defaulting to "live"; non-live names reject with
+// `channel_unsupported` until more channels ship. Rollback is promoting an
+// older ready version to the same channel.
 export const versionPromoteSchema = z
     .object({
     channel: z
@@ -728,9 +771,29 @@ export const versionPromoteSchema = z
 })
     .optional()
     .default({});
+/**
+ * `?async=1` on a route that otherwise waits for the work to settle: the route
+ * answers with the operation handle to poll instead. Every such route builds its
+ * query schema here so the accepted spellings stay one definition; the caller
+ * passes the description because that is the only per-route part.
+ *
+ * Plain enum (no zod transform): transforms cannot be represented in the
+ * generated OpenAPI spec, and this parameter must reach SDK consumers.
+ */
+export function asyncQuerySchema(description) {
+    return z.object({
+        async: z.enum(["true", "false", "1", "0"]).optional().describe(description),
+    });
+}
+/**
+ * Reads an {@link asyncQuerySchema} value. The factory owns which spellings the
+ * parameter accepts; this owns what they mean, so neither can drift alone.
+ */
+export function isAsyncRequested(value) {
+    return value === "true" || value === "1";
+}
 export const spaceFinalizeSchema = z
     .object({
-    conventionFiles: conventionFilesSchema.optional(),
     channel: z
         .enum(["live"])
         .nullable()
@@ -758,33 +821,35 @@ export const spaceRuntimeStatusSchema = z.object({
     operation: AsyncOperationSchema.nullable(),
     app: runtimeAppSchema
         .nullable()
-        .describe("What the live version runs: its Zero capsule and its Functions worker, each null when the published tree carries none of that product (both null for a static space). The whole object is null for callers whose credential does not carry `versions:read`, because app details read version contents, not serving state."),
-});
-export const spaceApplyChangeBaseSchema = z.object({
-    kind: z.enum(["variable", "routing", "access", "settings"]),
-    name: z.string(),
-    label: z.string(),
-});
-export const spaceApplyModeSchema = z.enum(["stage", "apply"]);
-export const spaceApplyChangeSchema = spaceApplyChangeBaseSchema.extend({
-    id: z.string(),
-    sourceSurface: z.string(),
-    applyMode: spaceApplyModeSchema,
-    before: z.record(z.string(), z.unknown()).nullable().optional(),
-    after: z.record(z.string(), z.unknown()).nullable().optional(),
-    metadata: z.record(z.string(), z.unknown()).optional(),
+        .describe("What the live version runs: its Zero capsule and its Functions worker, each null when the published tree carries none of that product (both null for a space without a runtime). The whole object is null for callers whose credential does not carry `versions:read`, because app details read version contents, not serving state."),
+    pendingApp: runtimeAppSchema
+        .nullable()
+        .describe("What the pending version would run — the same projection as `app`, read from `pendingVersionId`'s version so a dashboard can show what an in-flight publish is about to serve. Null when no publish is in flight, and null for callers without `versions:read`, exactly like `app`."),
 });
+/**
+ * Where a space's runtime stands against its desired state. `POST
+ * /v1/spaces/{spaceId}/apply` returns this in the platform mutation envelope,
+ * whose `operation` handle polls at `GET /v1/operations/{operationId}`; `GET
+ * /v1/spaces/{spaceId}/apply-state` returns the same shape as a plain read.
+ *
+ * None of these fields live on an operation record: the operation says whether
+ * the last apply ran, this says what the space is serving, what it wants to
+ * serve, and whether you may ask for it now.
+ */
 export const spaceApplyStateSchema = z.object({
-    status: z.enum(["live", "pending", "applying", "failed"]),
-    desiredRevision: z.string().nullable(),
-    appliedRevision: z.string().nullable(),
-    pendingChangeCount: z.number().int(),
-    changes: z.array(spaceApplyChangeSchema),
-    operation: AsyncOperationSchema.nullable(),
-    lastError: z.string().nullable(),
-    canApplyNow: z.boolean(),
-});
-export const spaceApplyResponseSchema = z.object({
-    applied: z.boolean(),
-    applyState: spaceApplyStateSchema,
+    status: z
+        .enum(["live", "pending", "applying", "failed"])
+        .describe("`live` when the runtime matches the desired state, `pending` when a change is waiting to be applied, `applying` while an apply is running, `failed` when the last apply failed."),
+    desiredRevision: z
+        .string()
+        .nullable()
+        .describe("Version the space wants to serve; null when nothing is pending."),
+    appliedRevision: z.string().nullable().describe("Version the runtime is serving now."),
+    lastError: z
+        .string()
+        .nullable()
+        .describe("Why the last apply failed; null unless `status` is `failed`."),
+    canApplyNow: z
+        .boolean()
+        .describe("Whether an apply would do something right now, for gating an Apply control."),
 });

package/dist/contracts/superadmin-activity.d.ts

@@ -14,6 +14,7 @@ export declare const superadminActivityEventQuerySchema: z.ZodObject<{
         system: "system";
         user: "user";
         api_key: "api_key";
+        partner_token: "partner_token";
         oauth_client: "oauth_client";
         anonymous_claim: "anonymous_claim";
     }>>;
@@ -64,7 +65,7 @@ export declare const SuperadminLatestUserSchema: z.ZodObject<{
     role: z.ZodNullable<z.ZodString>;
     banned: z.ZodBoolean;
     isAutomattician: z.ZodBoolean;
-    wpcom: z.ZodBoolean;
+    automatticBetaGrant: z.ZodBoolean;
     betaEnrolledAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -79,7 +80,7 @@ export declare const SuperadminLatestUserListSchema: z.ZodObject<{
         role: z.ZodNullable<z.ZodString>;
         banned: z.ZodBoolean;
         isAutomattician: z.ZodBoolean;
-        wpcom: z.ZodBoolean;
+        automatticBetaGrant: z.ZodBoolean;
         betaEnrolledAt: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
@@ -87,46 +88,6 @@ export declare const SuperadminLatestUserListSchema: z.ZodObject<{
         latestSessionAt: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const SuperadminLatestSpaceSchema: z.ZodObject<{
-    id: z.ZodString;
-    title: z.ZodString;
-    slug: z.ZodString;
-    status: z.ZodString;
-    tenantId: z.ZodString;
-    tenantName: z.ZodNullable<z.ZodString>;
-    teamId: z.ZodNullable<z.ZodString>;
-    teamSlug: z.ZodNullable<z.ZodString>;
-    teamName: z.ZodNullable<z.ZodString>;
-    externalCustomerId: z.ZodNullable<z.ZodString>;
-    siteId: z.ZodNullable<z.ZodString>;
-    siteStatus: z.ZodNullable<z.ZodString>;
-    liveHostname: z.ZodNullable<z.ZodString>;
-    disabledAt: z.ZodNullable<z.ZodString>;
-    deletedAt: z.ZodNullable<z.ZodString>;
-    createdAt: z.ZodString;
-    updatedAt: z.ZodString;
-}, z.core.$strip>;
-export declare const SuperadminLatestSpaceListSchema: z.ZodObject<{
-    spaces: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        title: z.ZodString;
-        slug: z.ZodString;
-        status: z.ZodString;
-        tenantId: z.ZodString;
-        tenantName: z.ZodNullable<z.ZodString>;
-        teamId: z.ZodNullable<z.ZodString>;
-        teamSlug: z.ZodNullable<z.ZodString>;
-        teamName: z.ZodNullable<z.ZodString>;
-        externalCustomerId: z.ZodNullable<z.ZodString>;
-        siteId: z.ZodNullable<z.ZodString>;
-        siteStatus: z.ZodNullable<z.ZodString>;
-        liveHostname: z.ZodNullable<z.ZodString>;
-        disabledAt: z.ZodNullable<z.ZodString>;
-        deletedAt: z.ZodNullable<z.ZodString>;
-        createdAt: z.ZodString;
-        updatedAt: z.ZodString;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
 export declare const SuperadminLatestVersionSchema: z.ZodObject<{
     id: z.ZodString;
     number: z.ZodNullable<z.ZodNumber>;
@@ -252,7 +213,6 @@ export declare const SuperadminBadExperienceListSchema: z.ZodObject<{
 export type SuperadminActivityEvent = z.infer<typeof SuperadminActivityEventSchema>;
 export type SuperadminActivityEventQuery = z.infer<typeof superadminActivityEventQuerySchema>;
 export type SuperadminLatestUser = z.infer<typeof SuperadminLatestUserSchema>;
-export type SuperadminLatestSpace = z.infer<typeof SuperadminLatestSpaceSchema>;
 export type SuperadminLatestVersion = z.infer<typeof SuperadminLatestVersionSchema>;
 export type SuperadminBadExperienceItem = z.infer<typeof SuperadminBadExperienceItemSchema>;
 export type SuperadminBadExperienceList = z.infer<typeof SuperadminBadExperienceListSchema>;