@spacefast/common 0.2.1 → 0.4.1

package/dist/contracts/zero-spacefast.d.ts

@@ -0,0 +1,444 @@
+import { z } from "zod";
+/**
+ * Bounds on the Space-scoped bearer a control-plane caller mints for an agent.
+ *
+ * Short enough that a leaked bearer expires before it is worth passing around,
+ * long enough for one agent session's worth of REST calls. The default is what
+ * `sf zero` asks for when nobody chose.
+ */
+export declare const SPACE_ZERO_TOKEN_MIN_TTL_SECONDS = 60;
+export declare const SPACE_ZERO_TOKEN_MAX_TTL_SECONDS = 3600;
+export declare const SPACE_ZERO_TOKEN_DEFAULT_TTL_SECONDS = 900;
+export declare const spaceZeroTokenRequestSchema: z.ZodObject<{
+    credentialId: z.ZodTemplateLiteral<`mch_${string}`>;
+    ttlSeconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type SpaceZeroTokenRequest = z.infer<typeof spaceZeroTokenRequestSchema>;
+export declare const spaceZeroTokenSchema: z.ZodObject<{
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+    host: z.ZodString;
+    endpoint: z.ZodString;
+    credentialId: z.ZodTemplateLiteral<`mch_${string}`>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+        "content.publish": "content.publish";
+        "access.manage": "access.manage";
+    }>>;
+    role: z.ZodNullable<z.ZodEnum<{
+        editor: "editor";
+        subscriber: "subscriber";
+        administrator: "administrator";
+    }>>;
+}, z.core.$strict>;
+export type SpaceZeroToken = z.infer<typeof spaceZeroTokenSchema>;
+/**
+ * What a caller must hold to reach an Ability.
+ *
+ * The two Ability origins authorize in two different vocabularies, and
+ * flattening them would say something false. A content-model Ability names
+ * Spacefast Grant capabilities, which the runtime checks against the
+ * capabilities this request's Grant carries. A platform Ability names one
+ * WordPress capability and lets WordPress decide, through the role
+ * content-principals.php projects from that same Grant. Same origin story, two
+ * different words — so the row says which one it is rather than pretending
+ * `upload_files` and a Grant capability are the same kind of thing.
+ */
+export declare const spaceZeroAbilityRequirementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"grant">;
+    capabilities: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"wordpress">;
+    capability: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type SpaceZeroAbilityRequirement = z.infer<typeof spaceZeroAbilityRequirementSchema>;
+/**
+ * One Ability a Space publishes, across every set it publishes one from.
+ *
+ * Two origins answer here and the row is deliberately uniform over both.
+ * Content-model Abilities are compiled at publish and bound to the version, so
+ * the live version is the authority and a rollback moves them with it. The
+ * `zero-wp-users` and `zero-storage` sets are registered by the runtime
+ * engine's own PHP; the control plane reads them from a mirror generated out of
+ * those same registrations (scripts/emit-zero-abilities.php), so enumerating
+ * them here is not a second source of truth — it is the first one, projected.
+ *
+ * Schemas are resolved, not referenced. A content-model Ability's schemas live
+ * in the release's schema table behind a pointer; a platform Ability's are
+ * inline in PHP. The catalog resolves the pointer so every row describes itself
+ * the same way and one consumer can generate types from all of them.
+ */
+export declare const spaceZeroAbilitySchema: z.ZodObject<{
+    name: z.ZodString;
+    id: z.ZodString;
+    category: z.ZodString;
+    mode: z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>;
+    requires: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"grant">;
+        capabilities: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"wordpress">;
+        capability: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    inputSchema: z.ZodNullable<z.ZodType<import("./content-model.js").ContentModelJsonValue, unknown, z.core.$ZodTypeInternals<import("./content-model.js").ContentModelJsonValue, unknown>>>;
+    outputSchema: z.ZodNullable<z.ZodType<import("./content-model.js").ContentModelJsonValue, unknown, z.core.$ZodTypeInternals<import("./content-model.js").ContentModelJsonValue, unknown>>>;
+}, z.core.$strict>;
+export type SpaceZeroAbility = z.infer<typeof spaceZeroAbilitySchema>;
+/**
+ * The content model the Space's live version publishes, whole.
+ *
+ * `listSpaceZeroAbilities` answers what an agent can call; this answers what
+ * the shapes are, in the form a type generator needs — the compiled release
+ * itself, schema table and all. The two are deliberately separate reads: the
+ * catalog is what a person or agent browses, and this is a build input that
+ * only a toolchain asks for.
+ *
+ * `versionId` is what the answer came from, so a generated artifact can name
+ * its source and a `--check` can say what moved. A Space with no live version,
+ * or a live version that declares no content model, answers with nulls rather
+ * than a 404: having no content model is an ordinary state, not a missing
+ * resource.
+ */
+export declare const spaceZeroContentModelSchema: z.ZodObject<{
+    versionId: z.ZodNullable<z.ZodString>;
+    model: z.ZodNullable<z.ZodObject<{
+        format: z.ZodLiteral<"spacefast.zero-wordpress">;
+        version: z.ZodLiteral<1>;
+        revision: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+        schemas: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+            sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            schema: z.ZodType<import("./content-model.js").ContentModelJsonValue, unknown, z.core.$ZodTypeInternals<import("./content-model.js").ContentModelJsonValue, unknown>>;
+        }, z.core.$strict>>;
+        wordpress: z.ZodObject<{
+            format: z.ZodLiteral<"spacefast.wordpress-content-model">;
+            version: z.ZodLiteral<1>;
+            resources: z.ZodArray<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentResourceId", "out">;
+                name: z.ZodString;
+                label: z.ZodString;
+                kind: z.ZodEnum<{
+                    media: "media";
+                    collection: "collection";
+                    posts: "posts";
+                    pages: "pages";
+                }>;
+                fields: z.ZodArray<z.ZodObject<{
+                    id: z.core.$ZodBranded<z.ZodString, "ContentFieldId", "out">;
+                    name: z.ZodString;
+                    label: z.ZodString;
+                    required: z.ZodBoolean;
+                    value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"text">;
+                        multiline: z.ZodBoolean;
+                        maxLength: z.ZodNullable<z.ZodNumber>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"number">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"boolean">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"datetime">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"blocks">;
+                        allowed: z.ZodUnion<readonly [z.ZodLiteral<"any">, z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentComponentId", "out">>]>;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"media">;
+                        multiple: z.ZodBoolean;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"reference">;
+                        target: z.core.$ZodBranded<z.ZodString, "ContentResourceId", "out">;
+                        multiple: z.ZodBoolean;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"enum">;
+                        values: z.ZodArray<z.ZodString>;
+                        multiple: z.ZodBoolean;
+                    }, z.core.$strict>], "kind">;
+                }, z.core.$strict>>;
+                publicRead: z.ZodBoolean;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        tables: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ContentTableId", "out">;
+            name: z.ZodString;
+            columns: z.ZodArray<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentFieldId", "out">;
+                name: z.ZodString;
+                nullable: z.ZodBoolean;
+                value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"string">;
+                    maxLength: z.ZodNullable<z.ZodNumber>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"number">;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"boolean">;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"datetime">;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"json">;
+                }, z.core.$strict>], "kind">;
+            }, z.core.$strict>>;
+            indexes: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                fields: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentFieldId", "out">>;
+                unique: z.ZodBoolean;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        abilities: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"query">;
+            mode: z.ZodLiteral<"read">;
+            id: z.core.$ZodBranded<z.ZodString, "ContentAbilityId", "out">;
+            input: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+            permits: z.ZodArray<z.ZodEnum<{
+                "page.view": "page.view";
+                "comments.read": "comments.read";
+                "comments.write": "comments.write";
+                "content.publish": "content.publish";
+                "access.manage": "access.manage";
+            }>>;
+            reads: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentResourceRef", "out">>;
+            writes: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentResourceRef", "out">>;
+            exposure: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"named">;
+                named: z.ZodLiteral<true>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"routed">;
+                named: z.ZodLiteral<true>;
+                route: z.ZodObject<{
+                    id: z.ZodString;
+                    method: z.ZodEnum<{
+                        POST: "POST";
+                        PUT: "PUT";
+                        GET: "GET";
+                        HEAD: "HEAD";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                        OPTIONS: "OPTIONS";
+                    }>;
+                    path: z.ZodString;
+                    admission: z.ZodEnum<{
+                        public: "public";
+                        authenticated: "authenticated";
+                    }>;
+                }, z.core.$strict>;
+            }, z.core.$strict>], "kind">;
+            cache: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"none">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"private">;
+                maxAgeSeconds: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"public">;
+                maxAgeSeconds: z.ZodNumber;
+                staleWhileRevalidateSeconds: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"mutation">;
+            mode: z.ZodLiteral<"write">;
+            id: z.core.$ZodBranded<z.ZodString, "ContentAbilityId", "out">;
+            input: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+            permits: z.ZodArray<z.ZodEnum<{
+                "page.view": "page.view";
+                "comments.read": "comments.read";
+                "comments.write": "comments.write";
+                "content.publish": "content.publish";
+                "access.manage": "access.manage";
+            }>>;
+            reads: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentResourceRef", "out">>;
+            writes: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentResourceRef", "out">>;
+            exposure: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"named">;
+                named: z.ZodLiteral<true>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"routed">;
+                named: z.ZodLiteral<true>;
+                route: z.ZodObject<{
+                    id: z.ZodString;
+                    method: z.ZodEnum<{
+                        POST: "POST";
+                        PUT: "PUT";
+                        GET: "GET";
+                        HEAD: "HEAD";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                        OPTIONS: "OPTIONS";
+                    }>;
+                    path: z.ZodString;
+                    admission: z.ZodEnum<{
+                        public: "public";
+                        authenticated: "authenticated";
+                    }>;
+                }, z.core.$strict>;
+            }, z.core.$strict>], "kind">;
+            cache: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"none">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"private">;
+                maxAgeSeconds: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"public">;
+                maxAgeSeconds: z.ZodNumber;
+                staleWhileRevalidateSeconds: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"endpoint">;
+            mode: z.ZodEnum<{
+                read: "read";
+                write: "write";
+            }>;
+            id: z.core.$ZodBranded<z.ZodString, "ContentAbilityId", "out">;
+            input: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+            permits: z.ZodArray<z.ZodEnum<{
+                "page.view": "page.view";
+                "comments.read": "comments.read";
+                "comments.write": "comments.write";
+                "content.publish": "content.publish";
+                "access.manage": "access.manage";
+            }>>;
+            reads: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentResourceRef", "out">>;
+            writes: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ContentResourceRef", "out">>;
+            exposure: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"named">;
+                named: z.ZodLiteral<true>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"routed">;
+                named: z.ZodLiteral<true>;
+                route: z.ZodObject<{
+                    id: z.ZodString;
+                    method: z.ZodEnum<{
+                        POST: "POST";
+                        PUT: "PUT";
+                        GET: "GET";
+                        HEAD: "HEAD";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                        OPTIONS: "OPTIONS";
+                    }>;
+                    path: z.ZodString;
+                    admission: z.ZodEnum<{
+                        public: "public";
+                        authenticated: "authenticated";
+                    }>;
+                }, z.core.$strict>;
+            }, z.core.$strict>], "kind">;
+            cache: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"none">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"private">;
+                maxAgeSeconds: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"public">;
+                maxAgeSeconds: z.ZodNumber;
+                staleWhileRevalidateSeconds: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>], "kind">>;
+        pages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            sourceKey: z.ZodString;
+            path: z.ZodString;
+            title: z.ZodString;
+            blockName: z.ZodLiteral<"zero/component">;
+            componentId: z.core.$ZodBranded<z.ZodString, "ContentComponentId", "out">;
+            props: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ContentSchemaId", "out">;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        hooks: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            runtime: z.ZodEnum<{
+                php: "php";
+                quickjs: "quickjs";
+            }>;
+            artifact: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            export: z.ZodString;
+        }, z.core.$strict>>;
+        syncBindings: z.ZodArray<z.ZodPipe<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ContentSyncBindingId", "out">;
+            resourceId: z.core.$ZodBranded<z.ZodString, "ContentResourceId", "out">;
+            fieldId: z.core.$ZodBranded<z.ZodString, "ContentFieldId", "out">;
+            source: z.ZodString;
+            publicPath: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodEnum<{
+                md: "md";
+                html: "html";
+                tsx: "tsx";
+            }>>;
+            compiled: z.ZodOptional<z.ZodObject<{
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>>;
+            documentSeed: z.ZodOptional<z.ZodObject<{
+                text: z.ZodString;
+                sha256: z.core.$ZodBranded<z.ZodString, "ContentModelSha256", "out">;
+            }, z.core.$strict>>;
+            slug: z.ZodString;
+        }, z.core.$strict>, z.ZodTransform<{
+            format: "md" | "html" | "tsx";
+            id: string & z.core.$brand<"ContentSyncBindingId">;
+            resourceId: string & z.core.$brand<"ContentResourceId">;
+            fieldId: string & z.core.$brand<"ContentFieldId">;
+            source: string;
+            slug: string;
+            publicPath?: string | undefined;
+            compiled?: {
+                sha256: string & z.core.$brand<"ContentModelSha256">;
+            } | undefined;
+            documentSeed?: {
+                text: string;
+                sha256: string & z.core.$brand<"ContentModelSha256">;
+            } | undefined;
+        }, {
+            id: string & z.core.$brand<"ContentSyncBindingId">;
+            resourceId: string & z.core.$brand<"ContentResourceId">;
+            fieldId: string & z.core.$brand<"ContentFieldId">;
+            source: string;
+            slug: string;
+            publicPath?: string | undefined;
+            format?: "md" | "html" | "tsx" | undefined;
+            compiled?: {
+                sha256: string & z.core.$brand<"ContentModelSha256">;
+            } | undefined;
+            documentSeed?: {
+                text: string;
+                sha256: string & z.core.$brand<"ContentModelSha256">;
+            } | undefined;
+        }>>>;
+        materializations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            resourceId: z.core.$ZodBranded<z.ZodString, "ContentResourceId", "out">;
+            fieldId: z.core.$ZodBranded<z.ZodString, "ContentFieldId", "out">;
+            directory: z.ZodString;
+            suffix: z.ZodString;
+            format: z.ZodEnum<{
+                md: "md";
+                html: "html";
+                tsx: "tsx";
+            }>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SpaceZeroContentModel = z.infer<typeof spaceZeroContentModelSchema>;

package/dist/contracts/zero-spacefast.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { contentModelJsonValueSchema, contentModelReleaseV1Schema } from "./content-model.js";
+import { grantCapabilitySchema } from "./grants-core.js";
+import { registeredIdSchema } from "./ids.js";
+import { wordpressPrincipalRoleSchema } from "./principal-assertion.js";
+// Spacefast's Zero surface: the control-plane API a Space's Zero capsule is
+// reached THROUGH — agent bearers minted against a Space's machine credential,
+// the Ability catalog a Space publishes, the content model a live version
+// carries. Every shape here names a host resource (a Space, a credential, a
+// Grant), which is why it is not part of the framework contract in `./zero.js`.
+/**
+ * Bounds on the Space-scoped bearer a control-plane caller mints for an agent.
+ *
+ * Short enough that a leaked bearer expires before it is worth passing around,
+ * long enough for one agent session's worth of REST calls. The default is what
+ * `sf zero` asks for when nobody chose.
+ */
+export const SPACE_ZERO_TOKEN_MIN_TTL_SECONDS = 60;
+export const SPACE_ZERO_TOKEN_MAX_TTL_SECONDS = 3_600;
+export const SPACE_ZERO_TOKEN_DEFAULT_TTL_SECONDS = 900;
+export const spaceZeroTokenRequestSchema = z
+    .object({
+    credentialId: registeredIdSchema("mch").describe("A live machine credential of this Space. Its canonical scoped Grant is the authority the Space's own runtime re-derives the WordPress role from."),
+    ttlSeconds: z
+        .number()
+        .int()
+        .min(SPACE_ZERO_TOKEN_MIN_TTL_SECONDS)
+        .max(SPACE_ZERO_TOKEN_MAX_TTL_SECONDS)
+        .default(SPACE_ZERO_TOKEN_DEFAULT_TTL_SECONDS)
+        .describe("How long the bearer stays valid, in seconds."),
+})
+    .strict();
+export const spaceZeroTokenSchema = z
+    .object({
+    token: z
+        .string()
+        .min(1)
+        .describe("Send as `X-SF-Authorization: Bearer <token>` to the Space's own REST surface — the plain Authorization header belongs to the customer's application and passes through untouched."),
+    expiresAt: z.string().datetime(),
+    host: z.string().min(1).describe("The serving host this bearer is bound to."),
+    endpoint: z.string().url().describe("The Space's WordPress REST root."),
+    credentialId: registeredIdSchema("mch"),
+    /**
+     * The named credential's Grant capabilities, which is what the serving
+     * Space re-derives its answer from. Re-derivation is per request and
+     * against the requested path, so a credential scoped away from a path
+     * answers there with less than this — never with more.
+     */
+    capabilities: z.array(grantCapabilitySchema),
+    role: wordpressPrincipalRoleSchema
+        .nullable()
+        .describe("The WordPress role those capabilities project to, or null when the request would reach WordPress as nobody."),
+})
+    .strict();
+/**
+ * What a caller must hold to reach an Ability.
+ *
+ * The two Ability origins authorize in two different vocabularies, and
+ * flattening them would say something false. A content-model Ability names
+ * Spacefast Grant capabilities, which the runtime checks against the
+ * capabilities this request's Grant carries. A platform Ability names one
+ * WordPress capability and lets WordPress decide, through the role
+ * content-principals.php projects from that same Grant. Same origin story, two
+ * different words — so the row says which one it is rather than pretending
+ * `upload_files` and a Grant capability are the same kind of thing.
+ */
+export const spaceZeroAbilityRequirementSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("grant"),
+        capabilities: z
+            .array(z.string().min(1))
+            .describe("Grant capabilities the caller must hold, all of them."),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("wordpress"),
+        capability: z
+            .string()
+            .min(1)
+            .describe("The WordPress capability the Ability's permission callback asks for."),
+    })
+        .strict(),
+]);
+/**
+ * One Ability a Space publishes, across every set it publishes one from.
+ *
+ * Two origins answer here and the row is deliberately uniform over both.
+ * Content-model Abilities are compiled at publish and bound to the version, so
+ * the live version is the authority and a rollback moves them with it. The
+ * `zero-wp-users` and `zero-storage` sets are registered by the runtime
+ * engine's own PHP; the control plane reads them from a mirror generated out of
+ * those same registrations (scripts/emit-zero-abilities.php), so enumerating
+ * them here is not a second source of truth — it is the first one, projected.
+ *
+ * Schemas are resolved, not referenced. A content-model Ability's schemas live
+ * in the release's schema table behind a pointer; a platform Ability's are
+ * inline in PHP. The catalog resolves the pointer so every row describes itself
+ * the same way and one consumer can generate types from all of them.
+ */
+export const spaceZeroAbilitySchema = z
+    .object({
+    name: z.string().min(1).describe("The name WordPress publishes the Ability under."),
+    id: z
+        .string()
+        .min(1)
+        .describe("The Ability's product id, before the Abilities API's flattening — `content.projects.list` for `zero/content-projects-list`."),
+    // Every ability set lists here as the catalog widens (users, storage,
+    // future features) — a literal would refuse rows the runtime legitimately
+    // serves.
+    category: z.string().min(1),
+    mode: z.enum(["read", "write"]),
+    requires: spaceZeroAbilityRequirementSchema,
+    inputSchema: contentModelJsonValueSchema
+        .nullable()
+        .describe("JSON Schema for the Ability's input, or null when it declares none."),
+    outputSchema: contentModelJsonValueSchema
+        .nullable()
+        .describe("JSON Schema for the Ability's output, or null when it declares none."),
+})
+    .strict();
+/**
+ * The content model the Space's live version publishes, whole.
+ *
+ * `listSpaceZeroAbilities` answers what an agent can call; this answers what
+ * the shapes are, in the form a type generator needs — the compiled release
+ * itself, schema table and all. The two are deliberately separate reads: the
+ * catalog is what a person or agent browses, and this is a build input that
+ * only a toolchain asks for.
+ *
+ * `versionId` is what the answer came from, so a generated artifact can name
+ * its source and a `--check` can say what moved. A Space with no live version,
+ * or a live version that declares no content model, answers with nulls rather
+ * than a 404: having no content model is an ordinary state, not a missing
+ * resource.
+ */
+export const spaceZeroContentModelSchema = z
+    .object({
+    versionId: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe("The live version this content model came from, or null when there is none."),
+    model: contentModelReleaseV1Schema
+        .nullable()
+        .describe("The compiled content model release, or null when the live version declares none."),
+})
+    .strict();

package/dist/contracts/zero-types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The module `sf zero types` writes into a Zero project.
+ *
+ * Three things a project's types depend on live in the platform rather than in
+ * the project's own source, and each one is only knowable by asking: the
+ * content model the live version compiled, the Ability catalog that version
+ * publishes alongside the engine's own sets, and the database schema the broker
+ * validates against. A capsule author can read all three from the dashboard and
+ * retype them by hand; this prints them instead.
+ *
+ * The output is self-contained on purpose — no imports, because it lands in
+ * someone else's project where a dependency on `@spacefast/common` would be an
+ * imposition. That is the same rule `contentModelSdkModule` follows, and its
+ * output is embedded here verbatim rather than re-derived: it already prints
+ * exactly the content-model half of this file.
+ */
+import type { ContentModelReleaseV1 } from "./content-model.js";
+import type { SpaceZeroAbility } from "./zero-spacefast.js";
+import type { ZeroTable } from "./zero.js";
+/** Everything a pull read, and where it read it from. */
+export type ZeroTypesSource = Readonly<{
+    /**
+     * The Space the types describe, or null for a local capsule compile.
+     *
+     * A project with no Space yet still has a content model and a database
+     * schema — its own, compiled locally — and the generated module is the same
+     * shape either way. What changes is what the header can honestly claim about
+     * where the types came from.
+     */
+    space: Readonly<{
+        id: string;
+        slug: string;
+    }> | null;
+    /** The live version the content model and catalog came from, when there is one. */
+    versionId: string | null;
+    abilities: readonly SpaceZeroAbility[];
+    contentModel: ContentModelReleaseV1 | null;
+    tables: readonly ZeroTable[];
+}>;
+/**
+ * Prints the whole `zero-types` module.
+ *
+ * Section order follows what a reader reaches for: the content model first
+ * because it is what most capsules are written against, then the Ability
+ * catalog that says what may be called and by whom, then the database rows.
+ */
+export declare function zeroTypesModule(source: ZeroTypesSource): string;