@spacefast/common 0.0.23 → 0.0.26

package/dist/contracts/grants.js

@@ -9,13 +9,6 @@ export const GRANT_CAPABILITIES = [
     "access.manage",
 ];
 export const grantCapabilitySchema = z.enum(GRANT_CAPABILITIES);
-export const GRANT_CAPABILITY_PRESETS = ["view", "comment", "publish", "manage"];
-export const GRANT_PRESET_CAPABILITIES = {
-    view: ["page.view"],
-    comment: ["page.view", "comments.read", "comments.write"],
-    publish: ["page.view", "content.publish"],
-    manage: ["page.view", "comments.read", "comments.write", "content.publish", "access.manage"],
-};
 export const GRANT_AUDIENCE_KINDS = [
     "public",
     "team",
@@ -714,12 +707,28 @@ export const identityConnectionPublicKeySchema = z
         .regex(/^[A-Za-z0-9_-]{43}$/, "publicKey must be a raw Ed25519 public key"),
 })
     .strict();
+/**
+ * Issuers the platform stamps on its own external Grants. A Team-configured
+ * connection may not claim one: the authority reference an external audience
+ * resolves to is derived from (issuer, subject), and these three resolve into
+ * the platform's own `member:` / `claim-preview:` / owner namespaces.
+ */
+export const RESERVED_IDENTITY_CONNECTION_ISSUERS = [
+    "spacefast-membership",
+    "claim-preview",
+    "spacefast-owner",
+];
+const identityConnectionIssuerSchema = z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((issuer) => !RESERVED_IDENTITY_CONNECTION_ISSUERS.includes(issuer.trim()), { message: "issuer is reserved by Spacefast" });
 export const identityConnectionCreateSchema = z.discriminatedUnion("type", [
     z
         .object({
         type: z.literal("oidc"),
         name: z.string().trim().min(1).max(200),
-        issuer: z.string().min(1).max(1024),
+        issuer: identityConnectionIssuerSchema,
         clientId: z.string().min(1).max(512),
         clientSecret: z.string().min(1).max(2048),
         sessionTtlSeconds: z
@@ -734,7 +743,7 @@ export const identityConnectionCreateSchema = z.discriminatedUnion("type", [
         .object({
         type: z.literal("signer"),
         name: z.string().trim().min(1).max(200),
-        issuer: z.string().min(1).max(1024),
+        issuer: identityConnectionIssuerSchema,
         authorizeUrl: z.string().min(1).max(2048),
         publicKeys: z.array(identityConnectionPublicKeySchema).min(1).max(5),
         sessionTtlSeconds: z.number().int().min(60).max(EXTERNAL_IDENTITY_MAX_TTL_SECONDS).optional(),

package/dist/contracts/ids.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-// Id prefix registry (internal-docs/platform.md "Id prefix registry", L1106-1127).
+// Id prefix registry (the platform spec "Id prefix registry").
 // Every PUBLIC resource registers a prefix here before it ships; ids are globally
 // unique and handle ids (operations, exports, imports, transfers, builds) are
 // fetchable at a top-level collection with no extra context. Control-plane-internal
@@ -49,7 +49,7 @@ export function registeredIdSchema(prefix) {
 }
 // The main Stattic tenant every self-serve team/user/resource lives under. A
 // well-known CONSTANT, never configuration: grammatically a normal tenant id with
-// zero special cases in contracts, policy URIs, or parsers (spec L1100-1105).
+// zero special cases in contracts, policy URIs, or parsers (per the platform spec).
 export const MAIN_TENANT_ID = "ten_main";
 /** Mint a globally unique id for a registered public resource prefix. */
 export function createId(prefix) {

package/dist/contracts/internal.d.ts

@@ -1,9 +1,4 @@
 import { z } from "zod";
-export declare const conventionFilesSchema: z.ZodObject<{
-    redirects: z.ZodOptional<z.ZodString>;
-    headers: z.ZodOptional<z.ZodString>;
-    routes: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 export declare const manifestFileSchema: z.ZodObject<{
     path: z.ZodString;
     size: z.ZodNumber;
@@ -11,6 +6,13 @@ export declare const manifestFileSchema: z.ZodObject<{
     contentType: z.ZodOptional<z.ZodString>;
     sourceUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const uploadManifestFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    size: z.ZodNumber;
+    sha256: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodString>;
+    sourceUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const pendingUploadSchema: z.ZodObject<{
     path: z.ZodString;
     size: z.ZodNumber;
@@ -91,7 +93,7 @@ export declare const uploadInstructionsSchema: 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";
             }>>>;

package/dist/contracts/internal.js

@@ -1,27 +1,27 @@
 import { z } from "zod";
 import { baseDiagnosticSchema } from "./common.js";
-export const conventionFilesSchema = z.object({
-    redirects: z.string().optional(),
-    headers: z.string().optional(),
-    routes: z.string().optional(),
-});
+const manifestSha256Schema = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters without a prefix.")
+    .describe("SHA-256 content digest: exactly 64 lowercase hex characters, no `sha256:` prefix (Version.manifestHash is the only prefixed form).");
+const manifestSourceUrlSchema = z
+    .string()
+    .url()
+    .describe("HTTPS URL the runtime can fetch directly instead of receiving local bytes.");
 export const manifestFileSchema = z.object({
     path: z
         .string()
         .describe("Version-relative POSIX path. Canonicalized at intake to UTF-8 NFC, percent-decoded exactly once; max 1,024 bytes in canonical form."),
     size: z.number().int().nonnegative().describe("File size in bytes."),
-    sha256: z
-        .string()
-        .regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters without a prefix.")
+    sha256: manifestSha256Schema
         .optional()
-        .describe("Optional SHA-256 content digest: exactly 64 lowercase hex characters, no `sha256:` prefix (Version.manifestHash is the only prefixed form). Omit it for fastest first uploads; include it on updates so unchanged files are never re-uploaded."),
+        .describe("Optional SHA-256 content digest: exactly 64 lowercase hex characters, no `sha256:` prefix (Version.manifestHash is the only prefixed form). Omit it to let the runtime hash uploaded bytes; include it to upload by content address, with the digest verified as the bytes land."),
     contentType: z.string().optional().describe("Optional content type for serving metadata."),
-    sourceUrl: z
-        .string()
-        .url()
+    sourceUrl: manifestSourceUrlSchema
         .optional()
         .describe("Optional HTTPS URL the runtime can fetch directly for this file instead of receiving bytes from the client."),
 });
+export const uploadManifestFileSchema = manifestFileSchema.describe("A declared upload file. sha256 is optional: omit it for runtime-hashed path uploads or sourceUrl fetches; include it for content-addressed uploads.");
 export const pendingUploadSchema = manifestFileSchema.pick({
     path: true,
     size: true,

package/dist/contracts/mcp.d.ts

@@ -155,6 +155,16 @@ export declare const hostedMcpDashboardResponseSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const hostedMcpProxyTokenSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export declare const hostedMcpProxyTokenResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        accessToken: z.ZodString;
+        expiresAt: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export declare const hostedMcpCloseSessionResponseSchema: z.ZodObject<{
     data: z.ZodObject<{
         sessionId: z.ZodString;
@@ -243,5 +253,6 @@ export declare const hostedMcpApprovalResponseSchema: z.ZodObject<{
 export type HostedMcpSession = z.infer<typeof hostedMcpSessionSchema>;
 export type HostedMcpSessionEvent = z.infer<typeof hostedMcpSessionEventSchema>;
 export type HostedMcpDashboard = z.infer<typeof hostedMcpDashboardSchema>;
+export type HostedMcpProxyToken = z.infer<typeof hostedMcpProxyTokenSchema>;
 export type HostedMcpPausedExecution = z.infer<typeof hostedMcpPausedExecutionSchema>;
 export type HostedMcpApprovalAction = z.infer<typeof hostedMcpApprovalActionSchema>;

package/dist/contracts/mcp.js

@@ -50,6 +50,11 @@ export const hostedMcpDashboardSchema = z.object({
     events: z.array(hostedMcpSessionEventSchema),
 });
 export const hostedMcpDashboardResponseSchema = dataEnvelope(hostedMcpDashboardSchema);
+export const hostedMcpProxyTokenSchema = z.object({
+    accessToken: z.string().min(1),
+    expiresAt: z.string().datetime(),
+});
+export const hostedMcpProxyTokenResponseSchema = dataEnvelope(hostedMcpProxyTokenSchema);
 export const hostedMcpCloseSessionResponseSchema = dataEnvelope(hostedMcpSessionSchema);
 export const hostedMcpSessionEventsResponseSchema = dataEnvelope(z.object({
     session: hostedMcpSessionSchema,

package/dist/contracts/me.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { betaEligibleTeamSourceSchema } from "./beta.js";
 import { planCodeSchema } from "./features.js";
-// `GET /v1/me` (internal-docs/platform.md route catalog): the authenticated
+// `GET /v1/me` (the platform spec route catalog): the authenticated
 // subject, its tenant grants, principal/team memberships, and a plan summary.
 // Works for every credential kind — sessions resolve their user and team
 // memberships; machine credentials resolve the teams and tenants their policy

package/dist/contracts/oauth-resources.d.ts

@@ -3,7 +3,7 @@ export declare const OAUTH_AUTHORIZATION_SERVER_PATH: "/v1/auth";
  * mcp origin (`https://mcp.<domain>`), so it has no path entry here. */
 export declare const OAUTH_API_RESOURCE_PATH: "/v1";
 export type OAuthResourceKey = "api" | "mcp";
-export declare const OAUTH_API_RESOURCE_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
+export declare const OAUTH_API_RESOURCE_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger"];
 export declare const OAUTH_MCP_TOOL_SCOPE: "mcp:tools";
 export declare const OAUTH_OFFLINE_ACCESS_SCOPE: "offline_access";
 export declare const OAUTH_MCP_RESOURCE_SCOPES: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
@@ -16,6 +16,7 @@ export declare const OAUTH_MCP_RESOURCE_SCOPES: readonly ["mcp:tools", "teams:re
  * is the list of capabilities the dashboard and CLI offer per agent account.
  */
 export declare const OAUTH_MCP_RESOURCE_ALLOWED_SCOPES: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
+export declare const OAUTH_API_RESOURCE_ALLOWED_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger", "offline_access"];
 /**
  * Interactive MCP clients should be useful after one consent. Authorization is
  * still bounded by the user's live team role and by approval gates around
@@ -23,13 +24,13 @@ export declare const OAUTH_MCP_RESOURCE_ALLOWED_SCOPES: readonly ["mcp:tools", "
  * capabilities. Machine clients may continue to request a narrower set.
  */
 export declare const OAUTH_MCP_DEFAULT_SCOPES: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
-export declare const OAUTH_PROVIDER_SCOPES: readonly ["openid", "profile", "email", "offline_access", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "mcp:tools"];
+export declare const OAUTH_PROVIDER_SCOPES: readonly ["openid", "profile", "email", "offline_access", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger", "mcp:tools"];
 export declare const OAUTH_RESOURCE_DEFINITIONS: {
     readonly api: {
         readonly key: "api";
         readonly name: "Spacefast API";
         readonly accessTokenTtlSeconds: number;
-        readonly allowedScopes: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
+        readonly allowedScopes: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger", "offline_access"];
     };
     readonly mcp: {
         readonly key: "mcp";

package/dist/contracts/oauth-resources.js

@@ -2,7 +2,7 @@ export const OAUTH_AUTHORIZATION_SERVER_PATH = "/v1/auth";
 /** The API resource is a path on the api origin; the MCP resource is the whole
  * mcp origin (`https://mcp.<domain>`), so it has no path entry here. */
 export const OAUTH_API_RESOURCE_PATH = "/v1";
-export const OAUTH_API_RESOURCE_SCOPES = [
+const OAUTH_SHARED_API_RESOURCE_SCOPES = [
     "teams:read",
     "teams:create",
     "spaces:read",
@@ -12,11 +12,16 @@ export const OAUTH_API_RESOURCE_SCOPES = [
     "domains:read",
     "domains:write",
 ];
+export const OAUTH_API_RESOURCE_SCOPES = [
+    ...OAUTH_SHARED_API_RESOURCE_SCOPES,
+    "spaces:publish",
+    "builds:trigger",
+];
 export const OAUTH_MCP_TOOL_SCOPE = "mcp:tools";
 export const OAUTH_OFFLINE_ACCESS_SCOPE = "offline_access";
 export const OAUTH_MCP_RESOURCE_SCOPES = [
     OAUTH_MCP_TOOL_SCOPE,
-    ...OAUTH_API_RESOURCE_SCOPES,
+    ...OAUTH_SHARED_API_RESOURCE_SCOPES,
 ];
 /**
  * A resource's `allowedScopes` is intersected with the requested scopes on every
@@ -30,6 +35,10 @@ export const OAUTH_MCP_RESOURCE_ALLOWED_SCOPES = [
     ...OAUTH_MCP_RESOURCE_SCOPES,
     OAUTH_OFFLINE_ACCESS_SCOPE,
 ];
+export const OAUTH_API_RESOURCE_ALLOWED_SCOPES = [
+    ...OAUTH_API_RESOURCE_SCOPES,
+    OAUTH_OFFLINE_ACCESS_SCOPE,
+];
 /**
  * Interactive MCP clients should be useful after one consent. Authorization is
  * still bounded by the user's live team role and by approval gates around
@@ -50,7 +59,7 @@ export const OAUTH_RESOURCE_DEFINITIONS = {
         key: "api",
         name: "Spacefast API",
         accessTokenTtlSeconds: 15 * 60,
-        allowedScopes: OAUTH_API_RESOURCE_SCOPES,
+        allowedScopes: OAUTH_API_RESOURCE_ALLOWED_SCOPES,
     },
     mcp: {
         key: "mcp",

package/dist/contracts/operations.d.ts

@@ -10,7 +10,6 @@ export declare const userOperationKindSchema: z.ZodEnum<{
     domain_transfer_submit: "domain_transfer_submit";
     domain_dns_apply: "domain_dns_apply";
     domain_lifecycle: "domain_lifecycle";
-    variable_cascade: "variable_cascade";
     webhook_deliver: "webhook_deliver";
     integration_release: "integration_release";
 }>;
@@ -44,7 +43,7 @@ export declare const UserOperationSchema: 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";
         }>>>;
@@ -65,7 +64,6 @@ export declare const UserOperationSchema: z.ZodObject<{
         domain_transfer_submit: "domain_transfer_submit";
         domain_dns_apply: "domain_dns_apply";
         domain_lifecycle: "domain_lifecycle";
-        variable_cascade: "variable_cascade";
         webhook_deliver: "webhook_deliver";
         integration_release: "integration_release";
     }>;
@@ -119,7 +117,7 @@ export declare const operationListResponseSchema: 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";
             }>>>;
@@ -140,7 +138,6 @@ export declare const operationListResponseSchema: z.ZodObject<{
             domain_transfer_submit: "domain_transfer_submit";
             domain_dns_apply: "domain_dns_apply";
             domain_lifecycle: "domain_lifecycle";
-            variable_cascade: "variable_cascade";
             webhook_deliver: "webhook_deliver";
             integration_release: "integration_release";
         }>;
@@ -162,3 +159,91 @@ export declare const operationListResponseSchema: z.ZodObject<{
         hasMore: z.ZodBoolean;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/** Buckets an operator triages by. Live buckets partition the live population:
+ *  a queued row is exactly one of ready / scheduled / blocked. */
+export declare const SUPERADMIN_OPERATION_FILTERS: readonly ["all", "ready", "scheduled", "blocked", "running", "stuck", "retrying", "failed", "succeeded", "canceled"];
+export type SuperadminOperationFilter = (typeof SUPERADMIN_OPERATION_FILTERS)[number];
+export declare const superadminOperationListQuerySchema: z.ZodObject<{
+    filter: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        failed: "failed";
+        canceled: "canceled";
+        ready: "ready";
+        running: "running";
+        succeeded: "succeeded";
+        scheduled: "scheduled";
+        blocked: "blocked";
+        stuck: "stuck";
+        retrying: "retrying";
+    }>>;
+    eventType: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    order: z.ZodDefault<z.ZodEnum<{
+        newest: "newest";
+        oldest: "oldest";
+    }>>;
+}, z.core.$strip>;
+export type SuperadminOperationListQuery = z.infer<typeof superadminOperationListQuerySchema>;
+export declare const SuperadminOperationRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    eventType: z.ZodString;
+    status: z.ZodString;
+    resourceType: z.ZodString;
+    resourceId: z.ZodString;
+    attempts: z.ZodNumber;
+    dueAt: z.ZodNullable<z.ZodString>;
+    leaseExpiresAt: z.ZodNullable<z.ZodString>;
+    stuck: z.ZodBoolean;
+    blockedByOperationId: z.ZodNullable<z.ZodString>;
+    inflightKey: z.ZodNullable<z.ZodString>;
+    lastError: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    finishedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const SuperadminOperationListSchema: z.ZodObject<{
+    operations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        eventType: z.ZodString;
+        status: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        attempts: z.ZodNumber;
+        dueAt: z.ZodNullable<z.ZodString>;
+        leaseExpiresAt: z.ZodNullable<z.ZodString>;
+        stuck: z.ZodBoolean;
+        blockedByOperationId: z.ZodNullable<z.ZodString>;
+        inflightKey: z.ZodNullable<z.ZodString>;
+        lastError: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        finishedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    windowHours: z.ZodNumber;
+}, z.core.$strip>;
+export declare const SuperadminOperationSummarySchema: z.ZodObject<{
+    windowHours: z.ZodNumber;
+    live: z.ZodObject<{
+        ready: z.ZodNumber;
+        scheduled: z.ZodNumber;
+        blocked: z.ZodNumber;
+        running: z.ZodNumber;
+        stuck: z.ZodNumber;
+        retrying: z.ZodNumber;
+    }, z.core.$strip>;
+    recent: z.ZodObject<{
+        succeeded: z.ZodNumber;
+        failed: z.ZodNumber;
+        canceled: z.ZodNumber;
+    }, z.core.$strip>;
+    oldestReadyAt: z.ZodNullable<z.ZodString>;
+    oldestRunningAt: z.ZodNullable<z.ZodString>;
+    kinds: z.ZodArray<z.ZodObject<{
+        eventType: z.ZodString;
+        ready: z.ZodNumber;
+        running: z.ZodNumber;
+        stuck: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/contracts/operations.js

@@ -11,7 +11,6 @@ export const userOperationKindSchema = z.enum([
     "domain_transfer_submit",
     "domain_dns_apply",
     "domain_lifecycle",
-    "variable_cascade",
     "webhook_deliver",
     "integration_release",
 ]);
@@ -33,15 +32,90 @@ export const operationListQuerySchema = cursorListQuerySchema.extend({
         .string()
         .min(1)
         .optional()
-        .describe("Filter to operations touching one resource type, e.g. `space`."),
+        .describe("Filter to operations touching one resource type, for example `space`."),
     resourceId: z.string().min(1).optional().describe("Filter to operations touching one resource."),
     spaceId: z
         .string()
         .min(1)
         .optional()
-        .describe("Filter to operations pertaining to one Space — its own operations plus those of its versions and builds. The Space must be readable by the caller."),
+        .describe("Filter to operations for one Space — its own operations plus those of its versions and builds. The Space must be readable by the caller."),
 });
 export const operationListResponseSchema = z.object({
     data: z.array(UserOperationSchema),
     pagination: CursorPaginationSchema,
 });
+// ---------------------------------------------------------------------------
+// Superadmin operator surface: the operations rows ARE the queue, bucketed by
+// claim eligibility. Served by the control plane's feed service and consumed
+// by the superadmin dashboard and the e2e harness.
+/** Buckets an operator triages by. Live buckets partition the live population:
+ *  a queued row is exactly one of ready / scheduled / blocked. */
+export const SUPERADMIN_OPERATION_FILTERS = [
+    "all",
+    "ready",
+    "scheduled",
+    "blocked",
+    "running",
+    "stuck",
+    "retrying",
+    "failed",
+    "succeeded",
+    "canceled",
+];
+export const superadminOperationListQuerySchema = z.object({
+    filter: z.enum(SUPERADMIN_OPERATION_FILTERS).default("all"),
+    eventType: z.string().trim().min(1).max(160).optional(),
+    limit: z.coerce.number().int().min(1).max(200).default(50),
+    order: z.enum(["newest", "oldest"]).default("newest"),
+});
+export const SuperadminOperationRowSchema = z.object({
+    id: z.string(),
+    eventType: z.string(),
+    status: z.string(),
+    resourceType: z.string(),
+    resourceId: z.string(),
+    attempts: z.number().int().nonnegative(),
+    // The mutable eligibility clock, meaningless once the row is terminal — null
+    // there rather than a stale instant an operator would read as a schedule.
+    dueAt: z.string().datetime().nullable(),
+    leaseExpiresAt: z.string().datetime().nullable(),
+    // Computed with the database clock so row labels agree with server-side
+    // stuck filters and summary totals even when an operator's clock drifts.
+    stuck: z.boolean(),
+    blockedByOperationId: z.string().nullable(),
+    inflightKey: z.string().nullable(),
+    lastError: z.string().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    finishedAt: z.string().datetime().nullable(),
+});
+export const SuperadminOperationListSchema = z.object({
+    operations: z.array(SuperadminOperationRowSchema),
+    total: z.number().int().nonnegative(),
+    windowHours: z.number().int().positive(),
+});
+export const SuperadminOperationSummarySchema = z.object({
+    windowHours: z.number().int().positive(),
+    live: z.object({
+        ready: z.number().int().nonnegative(),
+        scheduled: z.number().int().nonnegative(),
+        blocked: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+        stuck: z.number().int().nonnegative(),
+        retrying: z.number().int().nonnegative(),
+    }),
+    recent: z.object({
+        succeeded: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        canceled: z.number().int().nonnegative(),
+    }),
+    oldestReadyAt: z.string().datetime().nullable(),
+    oldestRunningAt: z.string().datetime().nullable(),
+    kinds: z.array(z.object({
+        eventType: z.string(),
+        ready: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+        stuck: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+    })),
+});

package/dist/contracts/pages.d.ts

@@ -1,29 +1,33 @@
 import { z } from "zod";
 export declare const SITE_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview"];
 export declare const sitePageIdSchema: z.ZodEnum<{
+    access: "access";
     denied: "denied";
-    index: "index";
     preview: "preview";
-    access: "access";
+    index: "index";
     404: "404";
 }>;
 export type SitePageId = z.infer<typeof sitePageIdSchema>;
 export declare const ROUTE_PAGE_IDS: readonly ["404", "denied", "access"];
 export declare const routePageIdSchema: z.ZodEnum<{
-    denied: "denied";
     access: "access";
+    denied: "denied";
     404: "404";
 }>;
 export type RoutePageId = z.infer<typeof routePageIdSchema>;
-export declare const CUSTOM_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview"];
+export declare const CUSTOM_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview", "collab"];
 export declare const customPageIdSchema: z.ZodEnum<{
+    collab: "collab";
+    access: "access";
     denied: "denied";
-    index: "index";
     preview: "preview";
-    access: "access";
+    index: "index";
     404: "404";
 }>;
 export type CustomPageId = z.infer<typeof customPageIdSchema>;
+export declare const COLLAB_PAGE_SOURCE = "_pages/collab.html";
+export declare const COLLAB_PAGE_PATH: "/_pages/collab.html";
+export declare const COLLAB_PAGE_ELEMENTS: readonly ["sf-space", "sf-comments", "sf-thread", "sf-timeline", "sf-presence", "sf-versions"];
 export declare const PLATFORM_PAGE_IDS: readonly ["undeployed", "suspended", "legal", "gone", "runtime-error", "rate-limited", "tier-unavailable", "proxy-error", "method-not-allowed", "content-too-large"];
 export declare const platformPageIdSchema: z.ZodEnum<{
     legal: "legal";
@@ -55,12 +59,13 @@ export declare const pageArtifactKeySchema: z.ZodString;
 export declare const runtimePagesSchema: z.ZodObject<{
     routes: z.ZodRecord<z.ZodString, z.ZodObject<{
         pages: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            denied: "denied";
             access: "access";
+            denied: "denied";
             404: "404";
         }>, z.ZodString>>;
         index: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     previews: z.ZodRecord<z.ZodString, z.ZodString>;
+    collab: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RuntimePages = z.infer<typeof runtimePagesSchema>;

package/dist/contracts/pages.js

@@ -3,8 +3,28 @@ export const SITE_PAGE_IDS = ["404", "denied", "access", "index", "preview"];
 export const sitePageIdSchema = z.enum(SITE_PAGE_IDS);
 export const ROUTE_PAGE_IDS = ["404", "denied", "access"];
 export const routePageIdSchema = z.enum(ROUTE_PAGE_IDS);
-export const CUSTOM_PAGE_IDS = ["404", "denied", "access", "index", "preview"];
+// `collab` is publishable but has no built-in template: with no layout of their
+// own a Space's reviewers get the platform frame at `/__/collab`, so there is
+// nothing for a default `_pages/collab.html` to be. Hence CUSTOM ⊃ SITE.
+export const CUSTOM_PAGE_IDS = ["404", "denied", "access", "index", "preview", "collab"];
 export const customPageIdSchema = z.enum(CUSTOM_PAGE_IDS);
+// The Space-level review room the collaboration orb expands into, and the URL
+// its compiled document answers at (collab-public-api.html §3). One room per
+// Space, so one page, at the root — never a per-directory override.
+// The PHP mirror is SPACEFAST_COLLAB_PAGE_PATH in runtime/engine/shared/context.php.
+export const COLLAB_PAGE_SOURCE = "_pages/collab.html";
+export const COLLAB_PAGE_PATH = `/${COLLAB_PAGE_SOURCE}`;
+// Registered by the browser SDK, not by the server: the compiler leaves them
+// in the document untouched and they render nothing at publish time. Listed
+// here only so a collab layout using them is not read as a typo'd page slot.
+export const COLLAB_PAGE_ELEMENTS = [
+    "sf-space",
+    "sf-comments",
+    "sf-thread",
+    "sf-timeline",
+    "sf-presence",
+    "sf-versions",
+];
 export const PLATFORM_PAGE_IDS = [
     "undeployed",
     "suspended",
@@ -87,4 +107,7 @@ export const runtimePagesSchema = z.object({
         index: pageArtifactKeySchema.optional(),
     })),
     previews: z.record(z.string().startsWith("/").max(2048), pageArtifactKeySchema),
+    // Present only when the Space published its own review room; its absence is
+    // what tells the SDK to expand into the platform frame instead.
+    collab: pageArtifactKeySchema.optional(),
 });

package/dist/contracts/plan-policy.d.ts

@@ -16,14 +16,12 @@ export type PlanDisabledBehavior = z.infer<typeof planDisabledBehaviorSchema>;
 export declare const PlanPolicyResponseSchema: z.ZodObject<{
     principal: z.ZodObject<{
         type: z.ZodEnum<{
-            site: "site";
             space: "space";
             team: "team";
             external_principal: "external_principal";
         }>;
         id: z.ZodString;
     }, z.core.$strip>;
-    siteId: z.ZodOptional<z.ZodString>;
     spaceId: z.ZodOptional<z.ZodString>;
     plan: z.ZodEnum<{
         free: "free";

package/dist/contracts/plan-policy.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { diagnosticSeverity } from "./enums.js";
 import { planCodeSchema, planLimitValueSchema } from "./features.js";
 // Behaviors the platform disables (rather than failing publishes) when the
-// plan does not include them (internal-docs/platform.md "Plans And Limits").
+// plan does not include them (the platform spec "Plans And Limits").
 export const PLAN_DISABLED_BEHAVIOR_CODES = [
     "free_external_proxy_disabled",
     "routing_rules_over_plan",
@@ -19,11 +19,10 @@ export const planDisabledBehaviorSchema = z.object({
 export const PlanPolicyResponseSchema = z.object({
     principal: z
         .object({
-        type: z.enum(["team", "site", "space", "external_principal"]),
+        type: z.enum(["team", "space", "external_principal"]),
         id: z.string(),
     })
         .describe("Principal the policy was resolved for."),
-    siteId: z.string().optional().describe("Site the policy was resolved against, when site-scoped."),
     spaceId: z
         .string()
         .optional()