@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/principal-assertion.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { registeredIdSchema } from "./ids.js";
+function isExactHttpOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return ((url.protocol === "https:" || url.protocol === "http:") &&
+        url.origin === value &&
+        url.pathname === "/" &&
+        url.search === "" &&
+        url.hash === "" &&
+        url.username === "" &&
+        url.password === "");
+}
+export const exactOriginSchema = z
+    .string()
+    .url()
+    .max(2_000)
+    .refine(isExactHttpOrigin, "must be an exact HTTP origin without path, credentials, query, or fragment")
+    .brand();
+const principalAudienceSchema = z
+    .object({
+    spaceId: registeredIdSchema("spc"),
+    runtimeInstanceId: z.string().min(1).max(255),
+    host: exactOriginSchema,
+})
+    .strict();
+const principalSubjectSchema = z
+    .object({
+    issuer: z.string().min(1).max(255),
+    subject: z.string().min(1).max(512),
+})
+    .strict();
+const principalAssertionFields = {
+    format: z.literal("spacefast.principal"),
+    version: z.literal(1),
+    audience: principalAudienceSchema,
+    sessionVersion: z.number().int().nonnegative(),
+    accessGeneration: z.number().int().nonnegative(),
+    nonce: z.string().min(16).max(512),
+    issuedAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().positive(),
+};
+export const principalAssertionV1Schema = z
+    .union([
+    z
+        .object({
+        ...principalAssertionFields,
+        actor: z.object({ kind: z.literal("user"), id: z.string().min(1).max(255) }).strict(),
+        subject: principalSubjectSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        ...principalAssertionFields,
+        actor: z.object({ kind: z.literal("service"), id: z.string().min(1).max(255) }).strict(),
+    })
+        .strict(),
+])
+    .refine((assertion) => assertion.expiresAt > assertion.issuedAt, {
+    path: ["expiresAt"],
+    message: "expiresAt must be after issuedAt",
+});

package/dist/contracts/principals.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * An external principal: the partner's own customer, as this platform knows it.
+ *
+ * A principal is materialized the first time it owns something here, never by
+ * registration — there is no "create principal" call, and the id is whatever
+ * the partner already calls that customer in its own system. `principalId` is
+ * therefore the partner's id verbatim, casing included; matching within a
+ * tenant is case-insensitive, so `Cus_ABC` and `cus_abc` are one principal and
+ * the first spelling seen is the one kept.
+ *
+ * `principalType` is a literal rather than the team/external union the resource
+ * refs use: teams are principals too, but they are addressed as teams and have
+ * their own surface. This resource exists to answer "who are my customers", and
+ * only external principals are.
+ */
+export declare const PrincipalSchema: z.ZodObject<{
+    principalType: z.ZodLiteral<"external">;
+    principalId: z.ZodString;
+    mode: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
+    spaceCount: z.ZodNumber;
+    status: z.ZodEnum<{
+        active: "active";
+        suspended: "suspended";
+        closed: "closed";
+    }>;
+    statusReason: z.ZodNullable<z.ZodString>;
+    statusChangedAt: z.ZodNullable<z.ZodString>;
+    statusActor: z.ZodNullable<z.ZodEnum<{
+        spacefast: "spacefast";
+        partner: "partner";
+    }>>;
+    assignedPlan: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type Principal = z.infer<typeof PrincipalSchema>;
+export declare const principalListSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        principalType: z.ZodLiteral<"external">;
+        principalId: z.ZodString;
+        mode: z.ZodEnum<{
+            live: "live";
+            test: "test";
+        }>;
+        spaceCount: z.ZodNumber;
+        status: z.ZodEnum<{
+            active: "active";
+            suspended: "suspended";
+            closed: "closed";
+        }>;
+        statusReason: z.ZodNullable<z.ZodString>;
+        statusChangedAt: z.ZodNullable<z.ZodString>;
+        statusActor: z.ZodNullable<z.ZodEnum<{
+            spacefast: "spacefast";
+            partner: "partner";
+        }>>;
+        assignedPlan: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PrincipalList = z.infer<typeof principalListSchema>;
+export declare const PrincipalParamsSchema: z.ZodObject<{
+    principalId: z.ZodString;
+}, z.core.$strip>;

package/dist/contracts/principals.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { principalLifecycleStatusSchema, principalStatusActorSchema } from "./commerce.js";
+import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+import { tenantMode } from "./enums.js";
+/**
+ * An external principal: the partner's own customer, as this platform knows it.
+ *
+ * A principal is materialized the first time it owns something here, never by
+ * registration — there is no "create principal" call, and the id is whatever
+ * the partner already calls that customer in its own system. `principalId` is
+ * therefore the partner's id verbatim, casing included; matching within a
+ * tenant is case-insensitive, so `Cus_ABC` and `cus_abc` are one principal and
+ * the first spelling seen is the one kept.
+ *
+ * `principalType` is a literal rather than the team/external union the resource
+ * refs use: teams are principals too, but they are addressed as teams and have
+ * their own surface. This resource exists to answer "who are my customers", and
+ * only external principals are.
+ */
+export const PrincipalSchema = z.object({
+    principalType: z
+        .literal("external")
+        .describe("Always `external`: teams are principals too, but they have their own surface."),
+    principalId: z
+        .string()
+        .describe("The partner's own id for this customer, in the casing it was first seen."),
+    mode: tenantMode.describe("`test` when this principal belongs to a linked test tenant, `live` otherwise."),
+    spaceCount: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Spaces this principal currently owns in the tenant."),
+    status: principalLifecycleStatusSchema.describe("Lifecycle status. `active` by default; `suspended` reversibly halts the principal's spaces and mutations; `closed` is terminal."),
+    statusReason: z
+        .string()
+        .nullable()
+        .describe("Free-text reason recorded with the last status change, or null."),
+    statusChangedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("When the status last changed, or null while never changed from the default."),
+    statusActor: principalStatusActorSchema
+        .nullable()
+        .describe("Who applied the current status: `partner` (the tenant) or `spacefast` (unliftable by the partner). Null while never changed."),
+    assignedPlan: z
+        .string()
+        .nullable()
+        .describe("Plan name assigned from the tenant's catalog, or null to fall back to defaultPlan."),
+    createdAt: z.string().datetime().describe("When this principal first owned something here."),
+    updatedAt: z.string().datetime().describe("When this principal was last seen owning something."),
+});
+export const principalListSchema = z.object({
+    data: z.array(PrincipalSchema),
+    pagination: CursorPaginationSchema,
+});
+export const PrincipalParamsSchema = z.object({
+    principalId: z.string().min(1).describe("The partner's own id for this customer."),
+});

package/dist/contracts/privacy.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export declare const privacySettingsSchema: z.ZodObject<{
+    analyticsOptOut: z.ZodBoolean;
+    advertisingOptOut: z.ZodBoolean;
+}, z.core.$strip>;
+export type PrivacySettings = z.infer<typeof privacySettingsSchema>;
+export declare const privacySettingsPatchSchema: z.ZodObject<{
+    analyticsOptOut: z.ZodOptional<z.ZodBoolean>;
+    advertisingOptOut: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PrivacySettingsPatch = z.infer<typeof privacySettingsPatchSchema>;

package/dist/contracts/privacy.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+// Account-level privacy choices, modeled on WordPress.com's `/me/settings`
+// pair (`tracks_opt_out`, `advertising_targeting_opt_out`). These are durable
+// server-side settings, distinct from the browser cookie-consent buckets: the
+// cookie answers "what may run in THIS browser", these answer "what may this
+// ACCOUNT's data be used for" on every device.
+export const privacySettingsSchema = z.object({
+    analyticsOptOut: z
+        .boolean()
+        .describe("Opt out of product analytics. When true, no analytics events are recorded for this account, in the browser or server-side."),
+    advertisingOptOut: z
+        .boolean()
+        .describe("Do-not-sell/share election (CCPA). When true, the account is excluded from any advertising or audience use."),
+});
+export const privacySettingsPatchSchema = privacySettingsSchema
+    .partial()
+    .describe("Fields to change; omitted fields are left alone.");

package/dist/contracts/problem-document.js

@@ -1,7 +1,6 @@
-// Reader for the RFC 9457 problem document every 4xx/5xx response carries, so the
-// client surfaces (CLI, MCP, SDK) share one definition of which members exist and
-// which values are trusted. Callers keep their own entry guards, message fallbacks
-// and public field names — this only extracts the wire members.
+// Reader for the RFC 9457 problem document every 4xx/5xx response carries, so
+// the CLI, MCP, and SDK share one definition of the wire members. Callers keep
+// their own entry guards, message fallbacks, and public field names.
 /** Returns undefined when the payload cannot be a problem document at all. */
 export function parseProblemDocument(payload) {
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) {

package/dist/contracts/publish-archive.d.ts

@@ -5,7 +5,7 @@ export declare const archivePublishReceiptSchema: z.ZodObject<{
         slug: z.ZodString;
         title: z.ZodString;
         publicName: z.ZodString;
-        defaultHostname: z.ZodString;
+        defaultHostname: z.ZodOptional<z.ZodString>;
         liveUrl: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
     build: z.ZodObject<{
@@ -30,6 +30,37 @@ export declare const archivePublishReceiptSchema: z.ZodObject<{
             branch: z.ZodOptional<z.ZodString>;
             pullRequestNumber: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>], "kind">;
+        source: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<{
+                build: "build";
+                agent: "agent";
+                api: "api";
+                dashboard: "dashboard";
+                cli: "cli";
+                git: "git";
+                direct_upload: "direct_upload";
+                import: "import";
+                variable_update: "variable_update";
+                config_update: "config_update";
+            }>;
+            client: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+            commit: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            dirty: z.ZodOptional<z.ZodBoolean>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            git: z.ZodOptional<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>>>;
+        }, z.core.$strip>>>;
         settingsSnapshot: z.ZodObject<{
             rootDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
             installDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -53,8 +84,8 @@ export declare const archivePublishReceiptSchema: 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>>;
@@ -86,7 +117,7 @@ export declare const archivePublishReceiptSchema: z.ZodObject<{
             finalizing: "finalizing";
             ready: "ready";
         }>;
-        immutableUrl: z.ZodString;
+        immutableUrl: z.ZodNullable<z.ZodString>;
         ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         number: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         manifestHash: z.ZodNullable<z.ZodString>;
@@ -114,6 +145,15 @@ export declare const archivePublishReceiptSchema: z.ZodObject<{
         retryAfter: z.ZodOptional<z.ZodNumber>;
         hint: z.ZodString;
     }, z.core.$strip>;
+    git: z.ZodOptional<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>>;
     access: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         token: z.ZodString;
@@ -129,8 +169,8 @@ export declare const archivePublishReceiptSchema: 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>>;
@@ -154,9 +194,8 @@ export declare const archivePublishReceiptSchema: z.ZodObject<{
 /**
  * `build` is the discriminant: a remote-build publish carries one, an ordinary
  * publish never does. The archive member is tried first because the ordinary
- * receipt would otherwise match a finished build's receipt (which also carries
- * a version and an activation) and silently strip the build off it, leaving
- * every caller's `"build" in receipt` check answering false.
+ * receipt also matches a finished build's receipt and would strip the build off
+ * it, leaving every caller's `"build" in receipt` check answering false.
  */
 export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObject<{
     space: z.ZodObject<{
@@ -164,7 +203,7 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         slug: z.ZodString;
         title: z.ZodString;
         publicName: z.ZodString;
-        defaultHostname: z.ZodString;
+        defaultHostname: z.ZodOptional<z.ZodString>;
         liveUrl: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
     build: z.ZodObject<{
@@ -189,6 +228,37 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
             branch: z.ZodOptional<z.ZodString>;
             pullRequestNumber: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>], "kind">;
+        source: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<{
+                build: "build";
+                agent: "agent";
+                api: "api";
+                dashboard: "dashboard";
+                cli: "cli";
+                git: "git";
+                direct_upload: "direct_upload";
+                import: "import";
+                variable_update: "variable_update";
+                config_update: "config_update";
+            }>;
+            client: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+            commit: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            dirty: z.ZodOptional<z.ZodBoolean>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            git: z.ZodOptional<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>>>;
+        }, z.core.$strip>>>;
         settingsSnapshot: z.ZodObject<{
             rootDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
             installDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -212,8 +282,8 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -245,7 +315,7 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
             finalizing: "finalizing";
             ready: "ready";
         }>;
-        immutableUrl: z.ZodString;
+        immutableUrl: z.ZodNullable<z.ZodString>;
         ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         number: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         manifestHash: z.ZodNullable<z.ZodString>;
@@ -273,6 +343,15 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         retryAfter: z.ZodOptional<z.ZodNumber>;
         hint: z.ZodString;
     }, z.core.$strip>;
+    git: z.ZodOptional<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>>;
     access: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         token: z.ZodString;
@@ -288,8 +367,8 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         code: z.ZodString;
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -315,7 +394,7 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         slug: z.ZodString;
         title: z.ZodString;
         publicName: z.ZodString;
-        defaultHostname: z.ZodString;
+        defaultHostname: z.ZodOptional<z.ZodString>;
         liveUrl: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
     access: z.ZodOptional<z.ZodObject<{
@@ -337,7 +416,7 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
             finalizing: "finalizing";
             ready: "ready";
         }>;
-        immutableUrl: z.ZodString;
+        immutableUrl: z.ZodNullable<z.ZodString>;
         ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         number: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         manifestHash: z.ZodNullable<z.ZodString>;
@@ -365,6 +444,23 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         retryAfter: z.ZodOptional<z.ZodNumber>;
         hint: z.ZodString;
     }, z.core.$strip>;
+    git: z.ZodOptional<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>>;
+    authMode: z.ZodOptional<z.ZodEnum<{
+        anonymous: "anonymous";
+        authenticated: "authenticated";
+    }>>;
+    persistence: z.ZodOptional<z.ZodEnum<{
+        managed: "managed";
+        temporary: "temporary";
+    }>>;
     operation: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodString;
@@ -388,8 +484,8 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -436,7 +532,8 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
             contentType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         links: z.ZodObject<{
-            resume: z.ZodString;
+            refresh: z.ZodString;
+            resume: z.ZodOptional<z.ZodString>;
             finalize: z.ZodString;
         }, z.core.$strip>;
         details: z.ZodOptional<z.ZodObject<{
@@ -452,8 +549,8 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
                 code: z.ZodString;
                 severity: z.ZodEnum<{
                     info: "info";
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -470,17 +567,17 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     claim: z.ZodOptional<z.ZodObject<{
+        expiresAt: z.ZodString;
         key: z.ZodString;
         url: z.ZodString;
         claimUrl: z.ZodString;
-        expiresAt: z.ZodString;
     }, z.core.$strip>>;
     diagnostics: z.ZodOptional<z.ZodArray<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>>;
@@ -495,6 +592,7 @@ export declare const publishResponseReceiptSchema: z.ZodUnion<readonly [z.ZodObj
         retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strip>>>;
     links: z.ZodOptional<z.ZodObject<{
+        refresh: z.ZodOptional<z.ZodString>;
         resume: z.ZodOptional<z.ZodString>;
         finalize: z.ZodOptional<z.ZodString>;
         promote: z.ZodOptional<z.ZodString>;

package/dist/contracts/publish-archive.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { publishedAccessSchema } from "./access.js";
 import { BuildSchema } from "./builds.js";
 import { baseDiagnosticSchema } from "./common.js";
+import { spaceGitSchema } from "./resources.js";
 import { publishActivationSchema, publishNextSchema, publishReceiptSchema, publishReceiptSpaceSchema, publishReceiptVersionSchema, spaceClaimReceiptSchema, } from "./spaces.js";
 export const archivePublishReceiptSchema = z.object({
     space: publishReceiptSpaceSchema,
@@ -9,6 +10,9 @@ export const archivePublishReceiptSchema = z.object({
     version: publishReceiptVersionSchema.optional(),
     activation: publishActivationSchema.optional(),
     next: publishNextSchema,
+    // Same block, same meaning as the ordinary receipt: a build publish is still
+    // a publish, and the caller still wants to know how to push the next one.
+    git: spaceGitSchema.optional(),
     access: publishedAccessSchema.optional(),
     claim: spaceClaimReceiptSchema.optional(),
     diagnostics: z.array(baseDiagnosticSchema).optional(),
@@ -22,9 +26,8 @@ export const archivePublishReceiptSchema = z.object({
 /**
  * `build` is the discriminant: a remote-build publish carries one, an ordinary
  * publish never does. The archive member is tried first because the ordinary
- * receipt would otherwise match a finished build's receipt (which also carries
- * a version and an activation) and silently strip the build off it, leaving
- * every caller's `"build" in receipt` check answering false.
+ * receipt also matches a finished build's receipt and would strip the build off
+ * it, leaving every caller's `"build" in receipt` check answering false.
  */
 export const publishResponseReceiptSchema = z.union([
     archivePublishReceiptSchema,

package/dist/contracts/push-new.d.ts

@@ -9,8 +9,8 @@ export declare const pushNewSessionStatusSchema: z.ZodEnum<{
     waiting_for_upload: "waiting_for_upload";
 }>;
 export declare const pushNewSourceKindSchema: z.ZodEnum<{
-    direct_upload: "direct_upload";
     git: "git";
+    direct_upload: "direct_upload";
 }>;
 export declare const pushNewUploadModeSchema: z.ZodEnum<{
     static_publish: "static_publish";
@@ -28,8 +28,8 @@ export declare const PushNewSessionSchema: z.ZodObject<{
         waiting_for_upload: "waiting_for_upload";
     }>;
     sourceKind: z.ZodEnum<{
-        direct_upload: "direct_upload";
         git: "git";
+        direct_upload: "direct_upload";
     }>;
     uploadMode: z.ZodNullable<z.ZodEnum<{
         static_publish: "static_publish";
@@ -86,8 +86,8 @@ export declare const PushNewCreateSessionResponseSchema: z.ZodObject<{
         waiting_for_upload: "waiting_for_upload";
     }>;
     sourceKind: z.ZodEnum<{
-        direct_upload: "direct_upload";
         git: "git";
+        direct_upload: "direct_upload";
     }>;
     uploadMode: z.ZodNullable<z.ZodEnum<{
         static_publish: "static_publish";
@@ -175,8 +175,8 @@ export declare const PushNewStatusResponseSchema: z.ZodObject<{
     spaceSlug: z.ZodString;
     errorCode: z.ZodNullable<z.ZodString>;
     sourceKind: z.ZodEnum<{
-        direct_upload: "direct_upload";
         git: "git";
+        direct_upload: "direct_upload";
     }>;
     remoteExpiresAt: z.ZodNullable<z.ZodString>;
     uploadMode: z.ZodNullable<z.ZodEnum<{

package/dist/contracts/quotas.js

@@ -1,8 +1,8 @@
 // Crude worst-case quotas (the platform spec "Abuse Posture"): hard,
 // launch-day abuse controls that exist independently of plan limits. One named
-// raise-only table — raising a limit later is a tweet, lowering one is a
-// betrayal. Enforcement points live in the control plane and reference these
-// names; every trip emits activity/ops events so thresholds are tuned from data.
+// raise-only table: raise a limit later, never lower one. Enforcement points
+// live in the control plane and reference these names; every trip emits
+// activity/ops events so thresholds are tuned from data.
 export const WORST_CASE_QUOTAS = {
     // Per-version artifact ceiling (sum of file bytes; enforced at manifest intake).
     maxArtifactBytes: 2 * 1024 * 1024 * 1024,

package/dist/contracts/realtime.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare 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 declare const resourceChangedNoticeSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"resource.changed">;
+    resource: z.ZodString;
+    spaceId: z.ZodString;
+    ids: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type ResourceChangedNoticePayload = z.infer<typeof resourceChangedNoticeSchema>;
+/**
+ * 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 declare function resourceChangedNotice(input: {
+    resource: string;
+    spaceId: string;
+    ids?: readonly string[] | undefined;
+}): ResourceChangedNoticePayload;