@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/comments.js

@@ -2,6 +2,13 @@ import { z } from "zod";
 import { accessRoleSchema, authorityReferenceSchema } from "./access.js";
 import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 export const commentThreadStatusSchema = z.enum(["open", "archived"]);
+/**
+ * What a moderator may ask a thread to become. Spam is not a stored status —
+ * Cast holds it as the thread's moderation state — so "spam" is a verdict the
+ * wire accepts, and reading a thread back always reports `open` or `archived`
+ * with `moderationState` beside it.
+ */
+export const commentThreadStatusPatchSchema = z.enum(["open", "archived", "spam"]);
 export const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
 export function normalizeCommentSearchQuery(value) {
     const trimmed = value?.trim();
@@ -32,8 +39,7 @@ export const commentCapabilitiesSchema = z
 });
 export const collaborationGuestProjectionSchema = z.object({
     anonymousId: z.string().min(8).max(160),
-    // No control or format characters: newlines, bidi overrides, and zero-width
-    // joiners in a self-asserted display name are only ever spoofing material.
+    // Control and format characters in a self-asserted name are spoofing material.
     name: z
         .string()
         .trim()
@@ -50,8 +56,7 @@ export const collaborationGuestProjectionSchema = z.object({
     emailVerified: z.boolean().default(false),
     capabilities: commentCapabilitiesSchema,
 });
-// The identity a browser asserts when requesting a guest ticket — the
-// self-asserted subset of the guest projection.
+// What a browser may assert about itself when requesting a guest ticket.
 export const commentsGuestIdentitySchema = collaborationGuestProjectionSchema.pick({
     anonymousId: true,
     name: true,
@@ -60,8 +65,7 @@ export const commentsGuestIdentitySchema = collaborationGuestProjectionSchema.pi
 export function commentCapabilitiesOf(capabilities) {
     return capabilities.filter((capability) => COMMENT_CAPABILITIES.includes(capability));
 }
-// The only account metadata exposed to Comments clients. Keep this shape
-// deliberately smaller than the private account record carried server-side.
+// The only account metadata exposed to Comments clients.
 export const collaborationPublicProfileSchema = z
     .object({
     name: z.string().trim().min(1).max(120).nullable(),
@@ -73,12 +77,10 @@ export const collaborationPublicProfileSchema = z
 })
     .strict();
 /**
- * Where the browser holding this ticket is.
- *
- * "embed" is a third-party site the owner allowlisted, and it is its own state
- * precisely so nothing pretends a foreign origin is a published Spacefast host:
- * the room an embed ticket names is origin-scoped, and both the mint and Cast
- * refuse the pairing in either direction.
+ * Where the browser holding this ticket is. "embed" is a third-party site the
+ * owner allowlisted, kept a separate state so no foreign origin passes as a
+ * published host: an embed ticket's room is origin-scoped, and both the mint
+ * and Cast refuse the pairing in either direction.
  */
 export const collaborationSurfaceSchema = z.enum(["published", "preview", "embed"]);
 export const collaborationTicketClaimsSchema = z
@@ -116,11 +118,9 @@ export const collaborationTicketClaimsSchema = z
     .superRefine((claims, context) => {
     if (claims.actorKind !== "guest")
         return;
-    // A guest ticket names an anonymous browser identity, and one grant always
-    // admitted it: the guest projection the mint builds carries all five of
-    // these or it is not a guest at all. Capabilities still come from the union
-    // of every authority the session holds — the admitting grant describes the
-    // admission, not the reach.
+    // The mint's guest projection carries all five or it is not a guest. The
+    // admitting grant describes the admission; capabilities come from the union
+    // of every authority the session holds.
     for (const field of [
         "anonymousId",
         "grantId",
@@ -136,9 +136,8 @@ export const collaborationTicketClaimsSchema = z
             });
         }
     }
-    // Identity never follows from an authority, but the reverse still holds:
-    // an anonymous principal can only ever have acquired credential-class
-    // authorities. Account-class references on a guest ticket are a forgery.
+    // An anonymous principal can only ever have acquired credential-class
+    // authorities, so an account-class reference on a guest ticket is a forgery.
     for (const [index, authority] of (claims.authorities ?? []).entries()) {
         if (!authority.startsWith("link:") && !authority.startsWith("password:")) {
             context.addIssue({
@@ -149,21 +148,20 @@ export const collaborationTicketClaimsSchema = z
         }
     }
 });
-// Where comments are reachable. One escalating axis, not two booleans: "off"
-// means nowhere, "previews" means the immutable Version hosts only, and
-// "everywhere" adds the published Space. Moving between them never requires a
-// republish — the always-injected inert tag re-reads the surface through the
-// runtime's same-origin Comments config exchange on every load.
+// Where comments are reachable, as one escalating axis: "off" is nowhere,
+// "previews" is the immutable Version hosts only, "everywhere" adds the
+// published Space. Moving between them never requires a republish: the inert
+// tag re-reads the surface through the runtime's config exchange on every load.
+/** Where a team without the collab.comments feature applies for access. */
+export const COMMENTS_WAITLIST_URL = "https://spacefast.com/waitlists/collab";
 export const commentsSurfaceSchema = z.enum(["off", "previews", "everywhere"]);
 export const COMMENTS_EMBED_ORIGINS_MAX = 20;
 /**
- * A site the Space owner allows the one-line Collab insert to run on.
- *
- * Exactly one https origin — scheme, host, and port, nothing else. No
- * wildcards: on a foreign site this list IS the entitlement, and `*.example.com`
- * hands it to every subdomain the site ever loses control of. An off-shape
- * value is refused rather than normalized, so what the owner typed and what the
- * server matches are the same string.
+ * A site the Space owner allows the one-line Collab insert to run on. Exactly
+ * one https origin, nothing else: on a foreign site this list IS the
+ * entitlement, and `*.example.com` hands it to every subdomain the site ever
+ * loses control of. An off-shape value is refused rather than normalized, so
+ * the owner's string and the matched string are the same.
  */
 export const commentsEmbedOriginSchema = z
     .string()
@@ -182,9 +180,8 @@ export const collaborationSettingsSchema = z
     .object({
     spamFilterEnabled: z.boolean().optional(),
     surface: commentsSurfaceSchema.default("previews"),
-    // Non-empty is the embed toggle — there is no fourth `surface` state. An
-    // embed origin sees the Space at its "previews" tier and never the
-    // published Space itself.
+    // Non-empty is the embed toggle; there is no fourth `surface` state. An embed
+    // origin sees the Space at its "previews" tier, never the published Space.
     embedOrigins: z.array(commentsEmbedOriginSchema).max(COMMENTS_EMBED_ORIGINS_MAX).default([]),
     notificationPreferences: z
         .object({
@@ -225,11 +222,9 @@ export const collaborationUpdateSchema = z.object({
     settings: collaborationSettingsPatchSchema,
 });
 /**
- * The overlay's whole configuration, in one shape.
- *
- * Both lanes carry this: the Space's own origins get it from the runtime's
- * same-origin exchange, a third-party site fetches it over CORS keyed by
- * `data-space`. Only the transport differs — the SDK parses one shape.
+ * The overlay's whole configuration. Both lanes carry it: the Space's own
+ * origins from the runtime's same-origin exchange, a third-party site over CORS
+ * keyed by `data-space`. Only the transport differs.
  */
 export const collabOverlayConfigSchema = z.object({
     enabled: z.boolean(),
@@ -252,9 +247,8 @@ export const collabOverlayConfigSchema = z.object({
         notices: z.boolean(),
     }),
 });
-// What a third-party page may assert about itself. The display name only — the
-// anonymous id is the server's to own, and a browser that could choose one
-// could wear another visitor's identity.
+// What a third-party page may assert about itself: the display name only. A
+// browser that could choose its anonymous id could wear another visitor's.
 export const commentsEmbedIdentitySchema = collaborationGuestProjectionSchema.pick({
     name: true,
     namedByUser: true,
@@ -290,9 +284,8 @@ export const commentsTicketResponseSchema = z.object({
     }),
     /**
      * The same session, bound to the Space's notice room. Cast binds a ticket to
-     * exactly one room, so an overlay that also wants Space-level notices needs
-     * a second ticket — never a second access decision. Null when this Space has
-     * notices switched off.
+     * exactly one room, so Space-level notices need a second ticket, never a
+     * second access decision. Null when this Space has notices switched off.
      */
     notice: z
         .object({
@@ -311,11 +304,9 @@ export const realtimeTokenResponseSchema = z.object({
     }),
 });
 /**
- * A Space-level fact worth interrupting someone for. It travels as a `notice`
- * on the Space's notice room — never as an event in a page room — because it
- * is not conversation content: every open surface needs it regardless of which
- * page it happens to be sitting on, including surfaces (the dashboard) that
- * are in no page room at all.
+ * A Space-level fact worth interrupting someone for. It travels on the Space's
+ * notice room, never as a page-room event: every open surface needs it whatever
+ * page it is on, including the dashboard, which is in no page room at all.
  */
 export const noticePublishSchema = z.object({
     versionId: z.string().optional(),
@@ -340,8 +331,7 @@ export const COLLAB_VERSION_URLS_MAX_IDS = 50;
 export const collabVersionUrlSchema = z.object({
     id: z.string(),
     url: z.string(),
-    // number/createdAt let clients order versions by real recency instead of
-    // comparing opaque ids.
+    // Ordering by real recency, instead of comparing opaque ids.
     number: z.number().int().nullable(),
     createdAt: z.string().nullable(),
 });
@@ -359,14 +349,13 @@ export const commentAuthorSchema = z.object({
 });
 export const commentTargetSchema = z.record(z.string(), z.unknown()).nullable();
 /**
- * How many attachments one thread or reply may carry. Mirrors Cast's own
- * `@attachment_limit`: Cast is the authority that enforces it on write, this
- * bound is what REST readers can rely on.
+ * How many attachments one thread or reply may carry. Mirrors Cast's
+ * `@attachment_limit`: Cast enforces it on write, this is what REST readers get.
  */
 export const COMMENT_ATTACHMENT_MAX_COUNT = 10;
 /**
  * A pointer to a storage object on the Space's own runtime plus the descriptor
- * needed to render it — never a URL. Cast stores exactly this (snake_case) under
+ * needed to render it, never a URL. Cast stores exactly this (snake_case) under
  * `metadata.attachments`; the id is a bare 32-hex object id.
  */
 export const commentAttachmentSchema = z.object({
@@ -385,9 +374,8 @@ export const commentAttachmentSchema = z.object({
         .optional(),
 });
 /**
- * What a REST reader gets: the stored attachment plus a freshly composed read
- * URL. `url` is null when the runtime's revocable read key cannot be resolved —
- * an honest degraded read rather than a dead link or a dropped attachment.
+ * The stored attachment plus a freshly composed read URL. `url` is null when the
+ * runtime's revocable read key cannot be resolved.
  */
 export const commentAttachmentViewSchema = commentAttachmentSchema.extend({
     url: z.string().nullable(),
@@ -435,19 +423,36 @@ export const commentThreadSchema = z.object({
     updatedAt: z.string().datetime().nullable(),
 });
 export const commentListQuerySchema = cursorListQuerySchema.extend({
-    versionId: z.string().optional(),
-    status: commentThreadStatusSchema.optional(),
-    filter: z.enum(["open", "archived", "spam"]).optional(),
-    pagePath: z.string().max(COMMENT_PAGE_PATH_MAX_LENGTH).optional(),
-    q: z.string().trim().max(COMMENT_SEARCH_QUERY_MAX_LENGTH).optional(),
-    author: z.string().trim().max(160).optional(),
-    unread: z.stringbool().optional(),
-});
-export const commentSpamFeedbackSchema = z
-    .object({
-    commentId: z.string().min(1).optional(),
-})
-    .default({});
+    versionId: z.string().optional().describe("Return only threads anchored to this version."),
+    status: commentThreadStatusSchema
+        .optional()
+        .describe("Return only threads in this lifecycle state."),
+    filter: z
+        .enum(["open", "archived", "spam"])
+        .optional()
+        .describe("Named view. `open` and `archived` select a lifecycle state and win over `status`; `spam` lists the moderation-held threads, which requires comment-moderator access."),
+    pagePath: z
+        .string()
+        .max(COMMENT_PAGE_PATH_MAX_LENGTH)
+        .optional()
+        .describe("Return only threads anchored to this page path, for example `/pricing`."),
+    q: z
+        .string()
+        .trim()
+        .max(COMMENT_SEARCH_QUERY_MAX_LENGTH)
+        .optional()
+        .describe("Free-text search across thread and comment bodies."),
+    author: z
+        .string()
+        .trim()
+        .max(160)
+        .optional()
+        .describe("Return only threads started by this author name."),
+    unread: z
+        .stringbool()
+        .optional()
+        .describe("Return only threads that have unread comments for the caller."),
+});
 export const commentCreateSchema = z.object({
     pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
     body: z.string().min(1).max(16_000),
@@ -458,12 +463,37 @@ export const commentReplySchema = z.object({
     body: z.string().min(1).max(16_000),
     idempotencyKey: z.string().min(1).max(320).optional(),
 });
-export const commentPatchSchema = z.object({
-    status: commentThreadStatusSchema.optional(),
+export const commentReplyResponseSchema = z.looseObject({
+    status: z.enum(["inserted", "existing"]),
+    comment: z.looseObject({}),
+});
+export const commentPatchSchema = z
+    .object({
+    status: commentThreadStatusPatchSchema.optional(),
+    /**
+     * The held reply the verdict is about; the thread itself when absent. It
+     * only means something next to a spam verdict, so it is refused elsewhere
+     * rather than silently dropped.
+     */
+    spamCommentId: z.string().min(1).optional(),
+})
+    .superRefine((patch, context) => {
+    if (patch.spamCommentId && patch.status !== "spam" && patch.status !== "open") {
+        context.addIssue({
+            code: "custom",
+            path: ["spamCommentId"],
+            message: "spamCommentId requires status open or spam",
+        });
+    }
 });
 export const commentExportQuerySchema = z.object({
-    format: z.enum(["markdown", "json"]).default("markdown"),
-    status: commentThreadStatusSchema.optional(),
+    format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Export shape: `markdown` to read, `json` to process."),
+    status: commentThreadStatusSchema
+        .optional()
+        .describe("Export only threads in this lifecycle state."),
 });
 export const commentListResponseSchema = z.object({
     data: z.array(commentThreadSchema),

package/dist/contracts/commerce.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+/**
+ * Partner commerce contracts (companion spec `2026-08-23-partner-commerce-design.md`
+ * §2 usage, §3 entitlements, and §4 principal lifecycle.
+ *
+ * This is the single home for the commercial layer: the principal lifecycle
+ * status/actor vocabulary, the per-tenant plan catalog declared in the
+ * system-space manifest, and the imperative plan-assignment request. The
+ * principal directory shape (`principals.ts`) and the manifest schema
+ * (`space-config.ts`) both import from here, so the vocabulary has one owner.
+ */
+export declare const PRINCIPAL_LIFECYCLE_STATUSES: readonly ["active", "suspended", "closed"];
+export declare const principalLifecycleStatusSchema: z.ZodEnum<{
+    active: "active";
+    suspended: "suspended";
+    closed: "closed";
+}>;
+export type PrincipalLifecycleStatus = z.infer<typeof principalLifecycleStatusSchema>;
+export declare const PRINCIPAL_STATUS_ACTORS: readonly ["partner", "spacefast"];
+export declare const principalStatusActorSchema: z.ZodEnum<{
+    spacefast: "spacefast";
+    partner: "partner";
+}>;
+export type PrincipalStatusActor = z.infer<typeof principalStatusActorSchema>;
+export declare const PLAN_CATALOG_CAPS: {
+    /** Max distinct plans a tenant may declare. */
+    readonly plans: 64;
+    /** Max plan-name length (also the assigned-plan and defaultPlan bound). */
+    readonly planNameChars: 64;
+    /** A plan can grant at most every known feature key. */
+    readonly features: number;
+};
+export declare const QUOTA_ENFORCEMENT_POLICIES: readonly ["warn", "block"];
+export declare const quotaEnforcementPolicySchema: z.ZodEnum<{
+    warn: "warn";
+    block: "block";
+}>;
+export type QuotaEnforcementPolicy = z.infer<typeof quotaEnforcementPolicySchema>;
+export declare const planCatalogEntrySchema: z.ZodObject<{
+    features: z.ZodArray<z.ZodEnum<{
+        zero: "zero";
+        "plans.paid.available": "plans.paid.available";
+        "anonymous.publishing": "anonymous.publishing";
+        "beta.enrollment_gate": "beta.enrollment_gate";
+        "domains.search": "domains.search";
+        "domains.registration": "domains.registration";
+        "domains.dns_management": "domains.dns_management";
+        "domains.wpcom_dns": "domains.wpcom_dns";
+        "domains.domain_connect": "domains.domain_connect";
+        "domains.proxy_bindings": "domains.proxy_bindings";
+        "collab.notices": "collab.notices";
+        "collab.comments": "collab.comments";
+        "content.managed": "content.managed";
+        "sites.dedicated_runtime": "sites.dedicated_runtime";
+        "collab.drawing": "collab.drawing";
+        tags: "tags";
+        functions: "functions";
+        "spaces.slug_rename": "spaces.slug_rename";
+        "pages.templates": "pages.templates";
+        "branding.hide": "branding.hide";
+    }>>;
+    quotas: z.ZodObject<{
+        spaces: z.ZodOptional<z.ZodNumber>;
+        storageBytes: z.ZodOptional<z.ZodNumber>;
+        buildMinutesPerMonth: z.ZodOptional<z.ZodNumber>;
+        customDomains: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    quotaPolicy: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+}, z.core.$strict>;
+export type PlanCatalogEntry = z.infer<typeof planCatalogEntrySchema>;
+export declare const planCatalogSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    features: z.ZodArray<z.ZodEnum<{
+        zero: "zero";
+        "plans.paid.available": "plans.paid.available";
+        "anonymous.publishing": "anonymous.publishing";
+        "beta.enrollment_gate": "beta.enrollment_gate";
+        "domains.search": "domains.search";
+        "domains.registration": "domains.registration";
+        "domains.dns_management": "domains.dns_management";
+        "domains.wpcom_dns": "domains.wpcom_dns";
+        "domains.domain_connect": "domains.domain_connect";
+        "domains.proxy_bindings": "domains.proxy_bindings";
+        "collab.notices": "collab.notices";
+        "collab.comments": "collab.comments";
+        "content.managed": "content.managed";
+        "sites.dedicated_runtime": "sites.dedicated_runtime";
+        "collab.drawing": "collab.drawing";
+        tags: "tags";
+        functions: "functions";
+        "spaces.slug_rename": "spaces.slug_rename";
+        "pages.templates": "pages.templates";
+        "branding.hide": "branding.hide";
+    }>>;
+    quotas: z.ZodObject<{
+        spaces: z.ZodOptional<z.ZodNumber>;
+        storageBytes: z.ZodOptional<z.ZodNumber>;
+        buildMinutesPerMonth: z.ZodOptional<z.ZodNumber>;
+        customDomains: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    quotaPolicy: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+}, z.core.$strict>>;
+export type PlanCatalog = z.infer<typeof planCatalogSchema>;
+export declare const defaultPlanNameSchema: z.ZodString;
+export declare const materializedPlanCatalogSchema: z.ZodObject<{
+    plans: z.ZodRecord<z.ZodString, z.ZodObject<{
+        features: z.ZodArray<z.ZodEnum<{
+            zero: "zero";
+            "plans.paid.available": "plans.paid.available";
+            "anonymous.publishing": "anonymous.publishing";
+            "beta.enrollment_gate": "beta.enrollment_gate";
+            "domains.search": "domains.search";
+            "domains.registration": "domains.registration";
+            "domains.dns_management": "domains.dns_management";
+            "domains.wpcom_dns": "domains.wpcom_dns";
+            "domains.domain_connect": "domains.domain_connect";
+            "domains.proxy_bindings": "domains.proxy_bindings";
+            "collab.notices": "collab.notices";
+            "collab.comments": "collab.comments";
+            "content.managed": "content.managed";
+            "sites.dedicated_runtime": "sites.dedicated_runtime";
+            "collab.drawing": "collab.drawing";
+            tags: "tags";
+            functions: "functions";
+            "spaces.slug_rename": "spaces.slug_rename";
+            "pages.templates": "pages.templates";
+            "branding.hide": "branding.hide";
+        }>>;
+        quotas: z.ZodObject<{
+            spaces: z.ZodOptional<z.ZodNumber>;
+            storageBytes: z.ZodOptional<z.ZodNumber>;
+            buildMinutesPerMonth: z.ZodOptional<z.ZodNumber>;
+            customDomains: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        quotaPolicy: z.ZodOptional<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+        }>>;
+    }, z.core.$strict>>;
+    defaultPlan: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type MaterializedPlanCatalog = z.infer<typeof materializedPlanCatalogSchema>;
+export declare const PRINCIPAL_STATUS_REASON_CHARS = 512;
+export declare const principalSuspendSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PrincipalSuspend = z.infer<typeof principalSuspendSchema>;
+export declare const principalUnsuspendSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PrincipalUnsuspend = z.infer<typeof principalUnsuspendSchema>;
+export declare const principalCloseSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PrincipalClose = z.infer<typeof principalCloseSchema>;
+export declare const principalPlanAssignSchema: z.ZodObject<{
+    plan: z.ZodString;
+}, z.core.$strict>;
+export type PrincipalPlanAssign = z.infer<typeof principalPlanAssignSchema>;

package/dist/contracts/commerce.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { FEATURE_KEYS, featureKeySchema } from "./features.js";
+/**
+ * Partner commerce contracts (companion spec `2026-08-23-partner-commerce-design.md`
+ * §2 usage, §3 entitlements, and §4 principal lifecycle.
+ *
+ * This is the single home for the commercial layer: the principal lifecycle
+ * status/actor vocabulary, the per-tenant plan catalog declared in the
+ * system-space manifest, and the imperative plan-assignment request. The
+ * principal directory shape (`principals.ts`) and the manifest schema
+ * (`space-config.ts`) both import from here, so the vocabulary has one owner.
+ */
+// Principal lifecycle status (§4). `active` is the default; `suspended` is
+// reversible (spaces serve the suspended page, mutations rejected); `closed` is
+// terminal (retention window then deletion).
+export const PRINCIPAL_LIFECYCLE_STATUSES = ["active", "suspended", "closed"];
+export const principalLifecycleStatusSchema = z
+    .enum(PRINCIPAL_LIFECYCLE_STATUSES)
+    .describe("Principal lifecycle status: active, suspended (reversible), or closed (terminal).");
+// Who applied the current status. `partner` is the tenant's own management key;
+// `spacefast` is a platform-applied (legal/abuse) action the partner cannot
+// lift. The status surface distinguishes the actor so a Spacefast suspension is
+// visibly unliftable by the partner (§4).
+export const PRINCIPAL_STATUS_ACTORS = ["partner", "spacefast"];
+export const principalStatusActorSchema = z
+    .enum(PRINCIPAL_STATUS_ACTORS)
+    .describe("Actor that applied the current status: the partner, or Spacefast.");
+// Bounds for the plan catalog. Self-contained (not in SPACE_CONFIG_CAPS) so the
+// manifest schema imports from commerce, never the reverse. A plan may grant at
+// most every known feature; plan names are short arbitrary per-tenant strings.
+export const PLAN_CATALOG_CAPS = {
+    /** Max distinct plans a tenant may declare. */
+    plans: 64,
+    /** Max plan-name length (also the assigned-plan and defaultPlan bound). */
+    planNameChars: 64,
+    /** A plan can grant at most every known feature key. */
+    features: FEATURE_KEYS.length,
+};
+const planNameSchema = z.string().trim().min(1).max(PLAN_CATALOG_CAPS.planNameChars);
+// How a tripped quota is enforced (companion spec §3c). `block` rejects the
+// triggering mutation with a typed problem naming the quota; `warn` records an
+// event and lets the mutation through. Serving is NEVER cut by quota — only by
+// suspension (§4). Omitted = `block`.
+export const QUOTA_ENFORCEMENT_POLICIES = ["warn", "block"];
+export const quotaEnforcementPolicySchema = z
+    .enum(QUOTA_ENFORCEMENT_POLICIES)
+    .describe("How a tripped quota is enforced: warn (event only) or block (reject).");
+const quotaLimitSchema = z.number().int().safe().nonnegative();
+// One plan's entitlements: feature keys plus mutation-time quotas. Feature
+// names are validated against the live `FEATURE_KEYS` vocabulary.
+export const planCatalogEntrySchema = z
+    .object({
+    features: z
+        .array(featureKeySchema)
+        .max(PLAN_CATALOG_CAPS.features)
+        .describe("Feature keys this plan grants. Each must be a known Spacefast feature key."),
+    quotas: z
+        .object({
+        spaces: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Max spaces a principal on this plan may own. Omitted = no space-count cap."),
+        storageBytes: quotaLimitSchema
+            .optional()
+            .describe("Max measured bytes stored by the principal. Omitted = no storage cap."),
+        buildMinutesPerMonth: quotaLimitSchema
+            .optional()
+            .describe("Max build minutes in one UTC month. Omitted = no monthly build cap."),
+        customDomains: quotaLimitSchema
+            .optional()
+            .describe("Max active custom domains. Omitted = no custom-domain cap."),
+    })
+        .strict()
+        .describe("Quotas that the platform checks at the mutation that can exceed each limit."),
+    quotaPolicy: quotaEnforcementPolicySchema
+        .optional()
+        .describe("Enforcement policy for this plan's quotas. Omitted = block."),
+})
+    .strict()
+    .describe("Entitlements for one plan: granted features and enforced quotas.");
+// The per-tenant plan catalog: plan name → entitlements. Plan NAMES are
+// arbitrary per-tenant strings (the reseller's own vocabulary); feature keys
+// inside each plan are the fixed Spacefast vocabulary.
+export const planCatalogSchema = z
+    .record(planNameSchema, planCatalogEntrySchema)
+    .refine((plans) => Object.keys(plans).length <= PLAN_CATALOG_CAPS.plans, `at most ${PLAN_CATALOG_CAPS.plans} plans`)
+    .describe("Per-tenant plan catalog declared in the system-space manifest.");
+// The plan unassigned principals fall back to. A bare name here; the manifest
+// schema cross-checks it against the declared `plans` keys.
+export const defaultPlanNameSchema = planNameSchema.describe("Name of the plan unassigned principals fall back to. Must be a key in `plans`.");
+// What the plan-catalog materializer freezes onto the tenant: the declared
+// catalog paired with the manifest's `defaultPlan` (null when the manifest
+// declared `plans` without a default). Entitlement resolution reads this one
+// blob — the assigned plan resolves against `plans`, and an unassigned or
+// stale principal falls back to `defaultPlan`.
+export const materializedPlanCatalogSchema = z
+    .object({
+    plans: planCatalogSchema,
+    defaultPlan: defaultPlanNameSchema.nullable(),
+})
+    .strict()
+    .describe("Materialized per-tenant plan catalog: the declared plans plus the default plan name.");
+// The free-text reason a lifecycle transition records on the principal
+// (`external_principals.status_reason`, bounded by the column). Optional on
+// every transition; surfaced back on the principal so an operator sees why.
+export const PRINCIPAL_STATUS_REASON_CHARS = 512;
+const statusReasonSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(PRINCIPAL_STATUS_REASON_CHARS)
+    .describe("Free-text reason recorded with the status change.");
+// Suspend a principal (§4): reversibly darken its spaces (402 suspended page)
+// and reject its mutations. Idempotent.
+export const principalSuspendSchema = z
+    .object({ reason: statusReasonSchema.optional() })
+    .strict()
+    .describe("Suspend an external principal: its spaces serve the suspended page and writes are blocked.");
+// Lift a suspension (§4). A partner may only lift a suspension it applied; a
+// Spacefast-applied (legal/abuse) suspension is not liftable by the partner.
+export const principalUnsuspendSchema = z
+    .object({ reason: statusReasonSchema.optional() })
+    .strict()
+    .describe("Lift a principal suspension and restore its spaces.");
+// Close a principal (§4): terminal. Refused while the principal still owns
+// spaces unless `force` tombstones them in the same call. Idempotent.
+export const principalCloseSchema = z
+    .object({
+    reason: statusReasonSchema.optional(),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Tombstone the principal's remaining spaces instead of refusing the close."),
+})
+    .strict()
+    .describe("Close an external principal (terminal). Requires no owned spaces, or `force` to tombstone them.");
+// Imperative plan assignment (§3b): `PUT /v1/principals/{type}/{id}/plan` with a
+// plan name from the live manifest. Runtime state, not manifest config.
+export const principalPlanAssignSchema = z
+    .object({
+    plan: planNameSchema.describe("Plan name from the live system-space manifest to assign to this principal."),
+})
+    .strict()
+    .describe("Assign a principal to a plan from the tenant's live plan catalog.");

package/dist/contracts/common.d.ts

@@ -16,7 +16,7 @@ export declare const baseDiagnosticSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         registrar: "registrar";
-        wpcloud: "wpcloud";
+        infra: "infra";
         dns: "dns";
         runtime: "runtime";
     }>>>;
@@ -183,7 +183,7 @@ export declare const AsyncOperationSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             registrar: "registrar";
-            wpcloud: "wpcloud";
+            infra: "infra";
             dns: "dns";
             runtime: "runtime";
         }>>>;
@@ -227,7 +227,7 @@ export declare function mutationEnvelope<T extends z.ZodType>(data: T): z.ZodObj
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;