@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/realtime.js

@@ -0,0 +1,54 @@
+/**
+ * The realtime cache lane's wire contract: one schema, both ends of the socket.
+ *
+ * The control plane publishes `resource.changed` onto a Space's Cast notice room
+ * whenever a mutation moves something a dashboard reads back
+ * (`apps/control-plane/src/comments/notices.ts`), and the dashboard turns those
+ * notices into targeted query invalidations
+ * (`packages/app-shell/src/lib/realtime-invalidation.ts`). Nothing renders this
+ * notice — it is read by code only — so the two sides agreeing on the shape is
+ * the entire contract, and they agree by importing the same schema rather than
+ * by keeping two copies in step.
+ *
+ * This lane is deliberately not part of the HTTP API: it carries no data, only
+ * the name of what moved. A missed notice costs a later refetch, never
+ * correctness.
+ */
+import { z } from "zod";
+/** The notice kind. Shares the `notice` event with Cast's own comment kinds. */
+export const RESOURCE_CHANGED = "resource.changed";
+/**
+ * The payload shape.
+ *
+ * `resource` is singular and names the kind of thing that moved rather than a
+ * table or a query key, so the receiver can map it onto whatever keys it holds.
+ * `ids` is advisory and deliberately lenient: a notice may name exactly what
+ * moved or nothing at all, and a list a build cannot read falls back to the
+ * empty list — which reads as "the whole resource kind moved". The failure mode
+ * of a malformed notice should be a broader refresh, never a missed one.
+ *
+ * camelCase and self-contained: a receiver reads `resource`/`spaceId`/`ids` and
+ * nothing else. The snake_case fields that ride alongside on the wire belong to
+ * the rendered notice lanes that share this room.
+ */
+export const resourceChangedNoticeSchema = z.object({
+    kind: z.literal(RESOURCE_CHANGED),
+    resource: z.string().min(1),
+    spaceId: z.string().min(1),
+    ids: z.array(z.string()).optional().catch([]),
+});
+/**
+ * The publisher's only way to shape a notice.
+ *
+ * Omitting `ids` (or passing an empty list) sends no `ids` field at all — JSON
+ * has no undefined — which is the "this whole resource moved" signal: always
+ * correct, just less targeted.
+ */
+export function resourceChangedNotice(input) {
+    return resourceChangedNoticeSchema.parse({
+        kind: RESOURCE_CHANGED,
+        resource: input.resource,
+        spaceId: input.spaceId,
+        ids: input.ids === undefined || input.ids.length === 0 ? undefined : [...input.ids],
+    });
+}

package/dist/contracts/repository-connections.d.ts

@@ -138,10 +138,10 @@ export declare const repositoryImportRemoteSchema: z.ZodObject<{
         generic: "generic";
     }>>;
     credential: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    defaultBranch: z.ZodDefault<z.ZodString>;
     repositoryFullName: z.ZodString;
     repositoryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     repositoryName: z.ZodOptional<z.ZodString>;
-    defaultBranch: z.ZodDefault<z.ZodString>;
     productionBranch: z.ZodOptional<z.ZodString>;
     cloneUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     buildSettings: z.ZodOptional<z.ZodObject<{

package/dist/contracts/repository-connections.js

@@ -118,8 +118,12 @@ export const RepositoryWebhookDeliverySchema = z.object({
     updatedAt: z.string().datetime(),
 });
 export const repositoryWebhookDeliveryListQuerySchema = cursorListQuerySchema.extend({
-    connectionType: repositoryConnectionTypeSchema.optional(),
-    status: repositoryWebhookDeliveryStatusSchema.optional(),
+    connectionType: repositoryConnectionTypeSchema
+        .optional()
+        .describe("Return only deliveries for this connection type."),
+    status: repositoryWebhookDeliveryStatusSchema
+        .optional()
+        .describe("Return only deliveries in this processing state."),
 });
 export const repositoryWebhookDeliveryListResponseSchema = z.object({
     data: z.array(RepositoryWebhookDeliverySchema),

package/dist/contracts/resources.d.ts

@@ -3,8 +3,8 @@ export declare const DiagnosticSchema: z.ZodObject<{
     code: z.ZodString;
     severity: z.ZodEnum<{
         info: "info";
-        error: "error";
         warning: "warning";
+        error: "error";
     }>;
     message: z.ZodString;
     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -35,30 +35,65 @@ export declare const ChannelPointerSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ChannelPointer = z.infer<typeof ChannelPointerSchema>;
 export declare const spaceSettingsDigestSchema: z.ZodString;
+export declare const spaceInfrastructureSchema: z.ZodObject<{
+    region: z.ZodNullable<z.ZodString>;
+    runtimeInstanceId: z.ZodNullable<z.ZodString>;
+    providerMainHostname: z.ZodNullable<z.ZodString>;
+    provisioningState: z.ZodEnum<{
+        provisioning: "provisioning";
+        degraded: "degraded";
+        converged: "converged";
+    }>;
+}, z.core.$strip>;
+export type SpaceInfrastructure = z.infer<typeof spaceInfrastructureSchema>;
+export declare const spaceGitSchema: z.ZodObject<{
+    managedBy: z.ZodEnum<{
+        spacefast: "spacefast";
+        github: "github";
+    }>;
+    remoteUrl: z.ZodNullable<z.ZodString>;
+    repository: z.ZodNullable<z.ZodString>;
+    defaultBranch: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SpaceGit = z.infer<typeof spaceGitSchema>;
 export declare const SpaceSchema: z.ZodObject<{
     id: z.ZodString;
-    tenantId: z.ZodString;
-    providerRef: z.ZodNullable<z.ZodString>;
-    providerClientId: z.ZodNullable<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>>;
+    providerRef: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    providerClientId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     teamId: z.ZodNullable<z.ZodString>;
     teamSlug: z.ZodNullable<z.ZodString>;
-    principal: z.ZodNullable<z.ZodObject<{
+    principal: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         tenantId: z.ZodString;
         principalType: z.ZodEnum<{
             team: "team";
             external: "external";
         }>;
         principalId: z.ZodString;
+    }, z.core.$strip>>>;
+    infrastructure: z.ZodOptional<z.ZodObject<{
+        region: z.ZodNullable<z.ZodString>;
+        runtimeInstanceId: z.ZodNullable<z.ZodString>;
+        providerMainHostname: z.ZodNullable<z.ZodString>;
+        provisioningState: z.ZodEnum<{
+            provisioning: "provisioning";
+            degraded: "degraded";
+            converged: "converged";
+        }>;
     }, z.core.$strip>>;
     anonymous: z.ZodBoolean;
     slug: z.ZodString;
     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>;
@@ -185,6 +220,16 @@ export declare const SpaceSchema: z.ZodObject<{
     }, z.core.$strip>>;
     settingsDigest: z.ZodString;
     noindex: z.ZodBoolean;
+    pinnedAt: z.ZodNullable<z.ZodString>;
+    git: z.ZodNullable<z.ZodObject<{
+        managedBy: z.ZodEnum<{
+            spacefast: "spacefast";
+            github: "github";
+        }>;
+        remoteUrl: z.ZodNullable<z.ZodString>;
+        repository: z.ZodNullable<z.ZodString>;
+        defaultBranch: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
     operation: z.ZodNullable<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodString;
@@ -208,8 +253,8 @@ export declare const SpaceSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -229,15 +274,28 @@ export declare const SpaceSchema: z.ZodObject<{
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
 }, z.core.$strip>;
+export declare const CONSUMER_HIDDEN_SPACE_FIELDS: readonly ["tenantId", "mode", "principal", "providerRef", "providerClientId", "infrastructure"];
+export type ConsumerHiddenSpaceField = (typeof CONSUMER_HIDDEN_SPACE_FIELDS)[number];
+export declare const publishSourceGitSchema: z.ZodObject<{
+    repository: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    repositoryFullName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    repositoryUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    branch: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    branchAliasUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    commit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    commitSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pullRequestNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$catchall<z.ZodUnknown>>;
 export declare const PublishSourceSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         build: "build";
         agent: "agent";
         api: "api";
         dashboard: "dashboard";
-        direct_upload: "direct_upload";
         cli: "cli";
         git: "git";
+        direct_upload: "direct_upload";
         import: "import";
         variable_update: "variable_update";
         config_update: "config_update";
@@ -261,6 +319,23 @@ export declare const PublishSourceSchema: z.ZodObject<{
     }, z.core.$catchall<z.ZodUnknown>>>;
 }, z.core.$strip>;
 export type PublishSource = z.infer<typeof PublishSourceSchema>;
+export declare const VersionPublisherSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        system: "system";
+        user: "user";
+        api_key: "api_key";
+        partner_token: "partner_token";
+        oauth_client: "oauth_client";
+        anonymous_claim: "anonymous_claim";
+    }>;
+    displayName: z.ZodString;
+    avatarUrl: z.ZodNullable<z.ZodString>;
+    authorizedBy: z.ZodNullable<z.ZodObject<{
+        displayName: z.ZodString;
+        avatarUrl: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type VersionPublisher = z.infer<typeof VersionPublisherSchema>;
 export declare const VersionSchema: z.ZodObject<{
     id: z.ZodString;
     ref: z.ZodNullable<z.ZodString>;
@@ -272,9 +347,9 @@ export declare const VersionSchema: z.ZodObject<{
             agent: "agent";
             api: "api";
             dashboard: "dashboard";
-            direct_upload: "direct_upload";
             cli: "cli";
             git: "git";
+            direct_upload: "direct_upload";
             import: "import";
             variable_update: "variable_update";
             config_update: "config_update";
@@ -297,6 +372,22 @@ export declare const VersionSchema: z.ZodObject<{
             pullRequestNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$catchall<z.ZodUnknown>>>;
     }, z.core.$strip>>;
+    publisher: z.ZodNullable<z.ZodObject<{
+        type: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            api_key: "api_key";
+            partner_token: "partner_token";
+            oauth_client: "oauth_client";
+            anonymous_claim: "anonymous_claim";
+        }>;
+        displayName: z.ZodString;
+        avatarUrl: z.ZodNullable<z.ZodString>;
+        authorizedBy: z.ZodNullable<z.ZodObject<{
+            displayName: z.ZodString;
+            avatarUrl: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     status: z.ZodEnum<{
         failed: "failed";
         canceled: "canceled";
@@ -323,15 +414,15 @@ export declare const VersionSchema: z.ZodObject<{
     filesRemovedCount: z.ZodNumber;
     pendingUploads: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
-        size: z.ZodNumber;
-        sha256: z.ZodOptional<z.ZodString>;
         sourceUrl: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodOptional<z.ZodString>;
+        size: z.ZodNumber;
     }, z.core.$strip>>;
     skippedPaths: z.ZodArray<z.ZodString>;
     immutableUrl: z.ZodNullable<z.ZodString>;
     immutableUrlStatus: z.ZodNullable<z.ZodEnum<{
         ready: "ready";
-        converging: "converging";
+        pending: "pending";
     }>>;
     isCurrentProduction: z.ZodBoolean;
     siteTitle: z.ZodString;
@@ -439,8 +530,8 @@ export declare const VersionSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -466,8 +557,8 @@ export declare const VersionSchema: z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/contracts/resources.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AsyncOperationSchema, baseDiagnosticSchema } from "./common.js";
-import { publishSourceKind, versionStatus, spaceDisabledReasonCode, spaceStatus } from "./enums.js";
+import { publishSourceKind, tenantMode, versionStatus, spaceDisabledReasonCode, spaceStatus, VERSION_IN_FLIGHT_STATUSES, } from "./enums.js";
 import { pendingUploadSchema } from "./internal.js";
 import { spaceConfigSchema } from "./space-config.js";
 export const DiagnosticSchema = baseDiagnosticSchema.extend({
@@ -27,23 +27,97 @@ export const ChannelPointerSchema = z.object({
 export const spaceSettingsDigestSchema = z
     .string()
     .regex(/^[0-9a-f]{64}$/, "must be a 64-character lowercase hex sha256 digest");
+// Where a space actually runs. Partner tenants reconcile placement and health
+// against their own records, so this is the real handle set rather than a
+// status word: the region it was placed in, the runtime instance serving it,
+// the provider hostname that instance answers on, and one derived convergence
+// state. Every handle is null until the space is placed.
+export const spaceInfrastructureSchema = z.object({
+    region: z.string().nullable().describe("Concrete region the space's site was placed in."),
+    runtimeInstanceId: z.string().nullable().describe("Runtime instance serving this space."),
+    providerMainHostname: z
+        .string()
+        .nullable()
+        .describe("Primary hostname the provider answers on for this space's site."),
+    provisioningState: z
+        .enum(["provisioning", "converged", "degraded"])
+        .describe("Convergence of the space against its intended infrastructure: still being placed, matching intent, or failing to converge."),
+});
+/*
+ * Where a space's git remote is, and who owns it.
+ *
+ * The two cases are not the same offer. A Spacefast-hosted space hands out a
+ * remote you can push to, and pushing publishes. A space bound to a GitHub
+ * repository has GitHub as its source of truth: there is no remote to give out,
+ * because a direct push would be overwritten by the next sync. `managedBy` is
+ * the field a client branches on, so it never has to infer which world it is in
+ * from an absent one — `remoteUrl` is non-null exactly when it is `spacefast`,
+ * and `repository` exactly when it is `github`.
+ *
+ * Deliberately one flat object rather than a discriminated union: this schema
+ * is reachable from the Space resource and from every publish receipt, and a
+ * union here pushed the router's whole inferred type graph past TypeScript's
+ * instantiation-depth limit (api/structural-router.test.ts). The invariant that
+ * a union would have carried in the type is stated above and enforced by the
+ * one function that builds this block (push-new/space-git.ts).
+ *
+ * `remoteUrl` never carries a credential. Authentication is HTTP Basic with the
+ * username `t` and a space key or API key as the password, so the credential
+ * lives wherever that client already keeps it instead of being duplicated into
+ * a URL that lands in shell history and `git remote -v`.
+ */
+export const spaceGitSchema = z.object({
+    managedBy: z
+        .enum(["spacefast", "github"])
+        .describe("Who owns this space's git history. `spacefast`: push `remoteUrl` to publish. `github`: the space deploys from `repository` and direct pushes are refused."),
+    remoteUrl: z
+        .string()
+        .nullable()
+        .describe("Credential-free git remote to push to, or null when `managedBy` is `github`. Authenticate as HTTP Basic user `t` with a space key or API key as the password."),
+    repository: z
+        .string()
+        .nullable()
+        .describe("`owner/name` of the GitHub repository this space deploys from, else null."),
+    defaultBranch: z
+        .string()
+        .nullable()
+        .describe("Branch that publishes to the live channel when pushed."),
+});
+// Every `CONSUMER_HIDDEN_SPACE_FIELDS` member below is `.optional()` because
+// the consumer projection OMITS it rather than nulling it — absent means "not
+// your surface", null means "nothing here yet", and the response validator has
+// to accept both bodies from the one shared schema.
 export const SpaceSchema = z.object({
     id: z.string(),
-    tenantId: z.string(),
+    tenantId: z.string().optional(),
+    // Derived from the owning tenant, never stored on the space: `test` for a
+    // space under a linked test tenant, `live` otherwise. A platform-surface
+    // field like `tenantId` — stripped from the consumer view.
+    mode: tenantMode
+        .optional()
+        .describe("`test` when the owning tenant is a linked test tenant, `live` otherwise."),
     // Raw provider identity of the site this space IS — deliberately not hidden
     // behind an abstraction, because a platform tenant provisioning under its own
     // WP.Cloud client needs the real handle to reconcile against. Both are
     // platform-surface fields (like `tenantId` and `principal`): the public API
     // reference strips them, the platform document keeps them. Null until the
     // space is placed.
-    providerRef: z.string().nullable().describe("WP Cloud `atomic_site_id` serving this space."),
+    providerRef: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("WP Cloud `atomic_site_id` serving this space."),
     providerClientId: z
         .string()
         .nullable()
+        .optional()
         .describe("WP Cloud client identity (`pvc_...`) the space's site is provisioned under."),
     teamId: z.string().nullable(),
     teamSlug: z.string().nullable(),
-    principal: PrincipalRefSchema.nullable(),
+    principal: PrincipalRefSchema.nullable().optional(),
+    // Present only for callers holding `infrastructure:read` on the space's
+    // tenant; absent (not null) for everyone else.
+    infrastructure: spaceInfrastructureSchema.optional(),
     anonymous: z.boolean(),
     slug: z.string(),
     title: z.string(),
@@ -114,14 +188,56 @@ export const SpaceSchema = z.object({
     noindex: z
         .boolean()
         .describe("When true, the live production hostnames serve platform noindex directives. Immutable version and preview hostnames are always noindex regardless of this setting."),
+    pinnedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the space was pinned to the top of its team's space list, or null when it is not pinned. The pin is team-wide: everyone who can see the team sees it."),
+    git: spaceGitSchema
+        .nullable()
+        .describe("Git remote for this space, or null when it has no repository yet. Push to `remoteUrl` to publish."),
     operation: AsyncOperationSchema.nullable(),
     createdAt: z.string().datetime(),
     updatedAt: z.string().datetime(),
 });
+// The fields a consumer-class credential never sees on a Space. ONE source of
+// truth: the response serializer omits exactly these for consumer callers, and
+// the public API reference strips exactly these from the shared schemas. They
+// are tenancy, on-behalf-of identity, and raw infrastructure — meaningful to a
+// partner running spaces for its own customers, noise (or a leak) to everyone
+// else.
+//
+// It lives below SpaceSchema so `satisfies` can pin every name to a real field:
+// a typo, or a later rename on the schema, is a compile error here rather than
+// a field that quietly stops being hidden.
+export const CONSUMER_HIDDEN_SPACE_FIELDS = [
+    "tenantId",
+    "mode",
+    "principal",
+    "providerRef",
+    "providerClientId",
+    "infrastructure",
+];
 // PublishSource (the platform spec "PublishSource"): the single
 // provenance shape for how a version came to exist. Sent on publish/version
 // create and echoed on the Version resource. Structured CI/git detail beyond
 // the named fields rides in `metadata` (string values only).
+// The git block of a PublishSource, exported on its own so servers echoing
+// declared provenance can validate just this piece without reaching into the
+// parent schema's internals.
+export const publishSourceGitSchema = z
+    .object({
+    repository: z.string().nullable().optional(),
+    repositoryFullName: z.string().nullable().optional(),
+    repositoryUrl: z.string().nullable().optional(),
+    ref: z.string().nullable().optional(),
+    branch: z.string().nullable().optional(),
+    branchAliasUrl: z.string().nullable().optional(),
+    commit: z.string().nullable().optional(),
+    commitSha: z.string().nullable().optional(),
+    pullRequestNumber: z.number().nullable().optional(),
+})
+    .catchall(z.unknown());
 export const PublishSourceSchema = z.object({
     kind: publishSourceKind.describe("How this version was produced."),
     client: z
@@ -144,20 +260,27 @@ export const PublishSourceSchema = z.object({
         .record(z.string(), z.string())
         .optional()
         .describe("Additional provenance (repository, CI run URL, workflow, actor, ...)."),
-    git: z
-        .object({
-        repository: z.string().nullable().optional(),
-        repositoryFullName: z.string().nullable().optional(),
-        repositoryUrl: z.string().nullable().optional(),
-        ref: z.string().nullable().optional(),
-        branch: z.string().nullable().optional(),
-        branchAliasUrl: z.string().nullable().optional(),
-        commit: z.string().nullable().optional(),
-        commitSha: z.string().nullable().optional(),
-        pullRequestNumber: z.number().nullable().optional(),
-    })
-        .catchall(z.unknown())
-        .optional(),
+    git: publishSourceGitSchema.optional(),
+});
+const VersionPublisherPersonSchema = z.object({
+    displayName: z.string().describe("The person's display name."),
+    avatarUrl: z
+        .string()
+        .nullable()
+        .describe("The person's avatar URL. The value is null when no avatar exists."),
+});
+export const VersionPublisherSchema = z.object({
+    type: z
+        .enum(["user", "api_key", "partner_token", "oauth_client", "anonymous_claim", "system"])
+        .describe("The type of actor that published the version."),
+    displayName: z
+        .string()
+        .describe("The display name of the person, agent, or system that published the version."),
+    avatarUrl: z
+        .string()
+        .nullable()
+        .describe("The publisher's avatar URL. The value is null when no avatar exists."),
+    authorizedBy: VersionPublisherPersonSchema.nullable().describe("The person who authorized the publisher. The value is null when the publisher is a person or has no known authorizer."),
 });
 export const VersionSchema = z.object({
     id: z.string(),
@@ -169,6 +292,7 @@ export const VersionSchema = z.object({
     number: z.number().int().positive().nullable(),
     spaceId: z.string(),
     source: PublishSourceSchema.nullable().describe("Publish provenance: who/what produced this version."),
+    publisher: VersionPublisherSchema.nullable().describe("The actor that published the version. The value is null for a legacy version with no attribution."),
     status: versionStatus,
     failureCode: z.string().nullable(),
     failureMessage: z.string().nullable(),
@@ -208,9 +332,9 @@ export const VersionSchema = z.object({
         .nullable()
         .describe("Permanent version URL (v{number}--{label}.view.fast form), computed once and stored at ready; survives slug changes, transfers, and channel repointing. Null before ready."),
     immutableUrlStatus: z
-        .enum(["converging", "ready"])
+        .enum(["pending", "ready"])
         .nullable()
-        .describe("Whether the immutable version URL provider alias has converged. converging means the URL may not resolve yet."),
+        .describe("Whether the immutable version URL is ready. pending means the URL might not resolve yet."),
     isCurrentProduction: z.boolean(),
     siteTitle: z.string(),
     config: spaceConfigSchema
@@ -228,7 +352,7 @@ export const VersionSchema = z.object({
     readyAt: z.string().datetime().nullable(),
     updatedAt: z.string().datetime(),
 });
-const activeVersionStatuses = new Set(["created", "uploading", "uploaded", "finalizing"]);
+const activeVersionStatuses = new Set(VERSION_IN_FLIGHT_STATUSES);
 export function hasActiveVersionStatus(status) {
     return Boolean(status && activeVersionStatuses.has(status));
 }