@spacefast/common 0.0.23 → 0.0.26

package/dist/contracts/functions.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { appRoutePathSchema, executionCapabilitiesSchema, executionLogEntrySchema, executionLogListQuerySchema, executionLogListResponseSchema, executionSha256Schema, httpMethodSchema, runtimeKindSchema, } from "./execution.js";
+import { appRoutePathSchema, executionBase64Schema, executionCapabilitiesSchema, executionSha256Schema, httpMethodSchema, } from "./execution.js";
 /**
  * Spacefast Functions: tenant workers run as Cloudflare Dynamic Workers.
  *
@@ -37,6 +37,13 @@ import { appRoutePathSchema, executionCapabilitiesSchema, executionLogEntrySchem
  * than transactional. That is why capsules are a different product rather
  * than a placement option — see `endpointIsPortable` in `./execution.js`.
  */
+/**
+ * The tag a compiled worker artifact carries — in `functionsSourceFinalizeSchema`
+ * and the runtime config built from it — so the PHP origin can tell what it is
+ * dispatching (`functions-dispatch.php` refuses a config tagged anything else).
+ * It is a property of the artifact the tree produced, not a kind a space or a
+ * version declares: a publish can carry this beside a capsule.
+ */
 export const FUNCTIONS_RUNTIME_KIND = "functions";
 export const FUNCTIONS_SOURCE_METADATA_KEY = "spacefastFunctions";
 export const FUNCTIONS_PLATFORM_ROUTE_PREFIX = "/__spacefast/functions";
@@ -44,7 +51,32 @@ export const FUNCTIONS_RUNTIME_ROUTE_PATHS = {
     logs: `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/logs`,
     /** Where a dispatched worker calls back for brokered capabilities. */
     relay: `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/relay`,
+    /**
+     * Where the execution host asks the space origin to drop cached responses —
+     * an OpenNext `revalidatePath` must reach the CDN in front of wp.cloud, and
+     * only the origin can speak for its own cache. Authenticated with the
+     * version-scoped purge credential in the `sf-purge-token` request header.
+     */
+    purge: `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/purge`,
 };
+/**
+ * The header the execution host presents at the origin purge route. Outside the
+ * `sf-fx-` namespace on purpose: that prefix names dispatch instructions the
+ * origin SENDS, and is stripped from anything inbound before tenant code — a
+ * purge call is the host speaking for itself, like a relay call.
+ */
+export const FUNCTIONS_PURGE_TOKEN_HEADER = "sf-purge-token";
+/**
+ * Where invocation counts are reported, on the CONTROL PLANE rather than the
+ * space origin.
+ *
+ * The two destinations are separate on purpose. Logs are the tenant's content
+ * and stay on their own origin; usage is a number the platform bills from and
+ * goes straight to us. Sharing one channel would make either destination a
+ * plausible place to look for the other's data, and would put log volume on the
+ * path that has to stay cheap.
+ */
+export const FUNCTIONS_USAGE_INTAKE_PATH = "/v1/runtime/functions/usage";
 /** Public, signed read path. Distinct from storage so the token is never a filename. */
 export const FUNCTIONS_BUNDLE_ROUTE_PREFIX = `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/b`;
 export const FUNCTIONS_RUNTIME_STORAGE_ROOT = "__spacefast/functions";
@@ -71,7 +103,17 @@ export const FUNCTIONS_RUNTIME_STORAGE_ROOT = "__spacefast/functions";
  * was never given.
  */
 export const FUNCTIONS_RUNTIME_BUNDLE_ROOT = `${FUNCTIONS_RUNTIME_STORAGE_ROOT}/bundles`;
+/**
+ * Where a version's Next-cache seed document lives — the build-time prerender
+ * and fetch-cache entries that warm the execution host's cache object so the
+ * first visitor gets the page the build rendered instead of a live re-render.
+ * A sibling of `bundles/` with the same properties: publishable through the
+ * ordinary upload path (its own carve-out in publish-policy), never servable
+ * as static content, read back only through the signed artifact route.
+ */
+export const FUNCTIONS_RUNTIME_SEED_ROOT = `${FUNCTIONS_RUNTIME_STORAGE_ROOT}/seeds`;
 export const FUNCTIONS_BUNDLE_FORMAT = "spacefast.functions.bundle.v1";
+export const FUNCTIONS_SEED_FORMAT = "spacefast.functions.seed.v1";
 /**
  * Ceiling on a bundle's decoded size.
  *
@@ -82,13 +124,66 @@ export const FUNCTIONS_BUNDLE_FORMAT = "spacefast.functions.bundle.v1";
  * modules are large, rather than at dispatch, where the tenant sees a 502.
  */
 export const FUNCTIONS_BUNDLE_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * Ceilings on the cache seed document. Per-entry mirrors the cache object's
+ * own row limit (an entry the object would refuse is dead weight in the
+ * document); the total bounds what the host pulls and ingests on a cold
+ * cache. Both are enforced in the CLI, where an overflow can say WHICH pages
+ * were left out — an omitted entry is not an error, it just renders live on
+ * first request like any cache miss.
+ */
+export const FUNCTIONS_SEED_ENTRY_MAX_BYTES = 2 * 1024 * 1024 - 8192;
+// The Durable Object buffers the JSON once, then decoding/parsing temporarily
+// holds the text and object graph beside it. Keep the document far below
+// Cloudflare's 128 MiB SHARED-isolate ceiling; several objects can occupy that
+// isolate, and the host enforces this bound again while streaming the response.
+export const FUNCTIONS_SEED_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * One warm-cache entry: exactly what the runtime's incremental-cache client
+ * would have written for `key` had it rendered the page itself. `valueJson`
+ * is carried as the JSON string it already is on disk (OpenNext's `.cache` /
+ * fetch-cache files) — re-parsing it here would only invite the seed writer
+ * and the cache client to disagree about serialization.
+ */
+export const functionsSeedEntrySchema = z
+    .object({
+    key: z.string().min(1).max(2048),
+    cacheType: z.enum(["cache", "fetch"]),
+    valueJson: z.string().min(1),
+    /** Epoch milliseconds the entry was built, so staleness math holds. */
+    lastModified: z.number().int().nonnegative(),
+})
+    .strict();
+/** The document served at a seed URL; host and CLI validate the same shape. */
+export const functionsSeedManifestSchema = z
+    .object({
+    format: z.literal(FUNCTIONS_SEED_FORMAT),
+    entries: z.array(functionsSeedEntrySchema),
+})
+    .strict();
 const functionsRoutePathSchema = appRoutePathSchema({
     subject: "Function routes",
 });
+/**
+ * How many entries the origin's dispatch table accepts.
+ *
+ * Exported because the CLI classifier has to compact its route claims BEFORE
+ * assembling the artifact — discovering the ceiling as a validation error at
+ * finalize would mean a build that classified fine fails at the last step — so
+ * the ceiling has to be a value both sides can read, not a literal each side
+ * spells for itself.
+ */
+export const FUNCTIONS_MAX_ROUTES = 256;
 /**
  * A worker's dynamic route table. Anything not matched here is answered from
  * the version's static content by wp.cloud and never reaches Cloudflare, which
  * is both the cheaper path and the one that keeps assets ours.
+ *
+ * A `subtree` entry covers its own path AND everything below it: the engine
+ * expands one into both `path` and `path/:splat`
+ * (`_stattic_runtime_functions_routes_artifact`, runtime/engine/admin/management.php),
+ * which is why `wholeSiteRoutes()` is a single `/` subtree entry and why an
+ * exact entry beside a subtree entry at the same path is dead weight.
  */
 export const functionsRouteSchema = z
     .object({
@@ -102,14 +197,17 @@ export const functionsRouteSchema = z
  * One module in a bundle, in the shape the Worker Loader consumes.
  *
  * `commonjs` exists because bundlers still emit it and rejecting it would fail
- * builds for a format the runtime accepts. Binary module types are deliberately
- * absent: nothing we build today emits them, and adding one later is additive.
+ * builds for a format the runtime accepts. Binary modules cross this JSON wire
+ * format as base64; the Functions host turns them back into ArrayBuffers at the
+ * Worker Loader boundary.
  */
 export const functionsBundleModuleSchema = z.union([
     z.object({ js: z.string() }).strict(),
     z.object({ cjs: z.string() }).strict(),
     z.object({ text: z.string() }).strict(),
     z.object({ json: z.unknown() }).strict(),
+    z.object({ wasm: executionBase64Schema }).strict(),
+    z.object({ data: executionBase64Schema }).strict(),
 ]);
 /**
  * The document served at a bundle URL and parsed by the host.
@@ -150,6 +248,25 @@ export const functionsBundleRefSchema = z
     size: z.number().int().nonnegative().max(FUNCTIONS_BUNDLE_MAX_BYTES),
 })
     .strict();
+/**
+ * Where a version's cache seed document sits in its content store — the
+ * bundle ref's sibling, with the seed's own root and ceiling. `entries` is
+ * carried so status surfaces can say what the seed holds without fetching it.
+ */
+export const functionsSeedRefSchema = z
+    .object({
+    path: z
+        .string()
+        .min(1)
+        .startsWith(`${FUNCTIONS_RUNTIME_SEED_ROOT}/`)
+        .refine((path) => !path.split("/").includes(".."), {
+        message: "Function seed paths cannot traverse outside the seed root.",
+    }),
+    sha256: executionSha256Schema,
+    size: z.number().int().nonnegative().max(FUNCTIONS_SEED_MAX_BYTES),
+    entries: z.number().int().nonnegative(),
+})
+    .strict();
 /**
  * The path a bundle is served from.
  *
@@ -171,6 +288,15 @@ export const functionsBundleRefSchema = z
 export function functionsBundlePath(input) {
     return `${FUNCTIONS_BUNDLE_ROUTE_PREFIX}/${bundleDigest(input.sha256)}/${input.token}/bundle.json`;
 }
+/**
+ * The seed document's read path — the bundle route with a different terminal
+ * filename and its own token audience. One signed artifact route on the
+ * origin serves both: the filename says what the digest names, the token's
+ * audience says what the caller was authorised to read.
+ */
+export function functionsSeedPath(input) {
+    return `${FUNCTIONS_BUNDLE_ROUTE_PREFIX}/${bundleDigest(input.sha256)}/${input.token}/seed.json`;
+}
 /**
  * Where the bundle actually sits in the published version — the same path minus
  * the token segment. The token authorises the read; it does not name the file,
@@ -179,6 +305,10 @@ export function functionsBundlePath(input) {
 export function functionsBundleStoragePath(input) {
     return `${FUNCTIONS_RUNTIME_BUNDLE_ROOT}/${bundleDigest(input.sha256)}/bundle.json`;
 }
+/** The seed's storage twin of `functionsBundleStoragePath`. */
+export function functionsSeedStoragePath(input) {
+    return `${FUNCTIONS_RUNTIME_SEED_ROOT}/${bundleDigest(input.sha256)}/seed.json`;
+}
 /**
  * The digest is carried in contracts as `sha256:<hex>` but appears in paths as
  * bare hex: a colon is legal in a path segment yet needlessly invites
@@ -211,9 +341,26 @@ export const functionsWorkerArtifactSchema = z
      */
     mainModule: z.string().min(1).max(1024),
     bundle: functionsBundleRefSchema,
+    /**
+     * The build-time cache seed, or null when the build produced nothing
+     * worth warming (no prerenders left with the worker, no fetch cache).
+     * A ref, not content: the document rides the version's own file tree
+     * like the bundle, and the host pulls it through a signed URL minted at
+     * finalize.
+     */
+    seed: functionsSeedRefSchema.nullable().default(null),
     compatibilityDate: functionsCompatibilityDateSchema,
     compatibilityFlags: z.array(z.string().min(1).max(128)).max(32).default([]),
-    routes: z.array(functionsRouteSchema).max(256).default([]),
+    routes: z.array(functionsRouteSchema).max(FUNCTIONS_MAX_ROUTES).default([]),
+    /**
+     * Cookie names whose presence must skip the origin's static fast path on
+     * claimed routes — the framework's draft/preview session markers. Data
+     * from the classifier, not names the engine knows: the origin checks the
+     * Cookie header against this list and dispatches instead of serving the
+     * extracted file, which is what lets a fully-static page still honor a
+     * draft session without a build-wide draft-usage proof.
+     */
+    bypassCookies: z.array(z.string().min(1).max(128)).max(8).default([]),
     /**
      * Aggregate of what the worker's handlers reach, used to decide which
      * brokered capabilities the relay will honour for this version. A worker
@@ -221,6 +368,18 @@ export const functionsWorkerArtifactSchema = z
      * so an injected dependency cannot widen authority at runtime.
      */
     capabilities: executionCapabilitiesSchema,
+    /**
+     * Platform-owned runtime services this build needs. This is deliberately
+     * separate from author capabilities: an OpenNext build needs durable cache
+     * storage even when the application itself declares no database or fetch
+     * access, and that storage must never become a general tenant credential.
+     */
+    platform: z
+        .object({
+        nextCache: z.boolean().default(false),
+    })
+        .strict()
+        .default({ nextCache: false }),
 })
     .strict();
 /**
@@ -232,13 +391,24 @@ export const functionsWorkerArtifactSchema = z
  * *grants*, resolved by the control plane at finalize so the origin forwards a
  * decision rather than making one. Anything absent fails closed at the relay.
  */
-export const FUNCTIONS_DISPATCH_CAPABILITIES = ["db.read", "db.write", "fetch", "log"];
+export const FUNCTIONS_DISPATCH_CAPABILITIES = [
+    "storage.read",
+    "storage.write",
+    "db.read",
+    "db.write",
+    "fetch",
+    "log",
+    "next.cache",
+    "gravatar.profile",
+    "spam.check",
+    "email.send",
+];
 export const functionsDispatchCapabilitySchema = z.enum(FUNCTIONS_DISPATCH_CAPABILITIES);
 /**
  * Resolves a build's declared capabilities into the grant a dispatch carries.
  *
- * Three of the six declared capabilities have no dispatch counterpart, and each
- * for its own reason:
+ * Three declared capabilities have no dispatch counterpart, each for its own
+ * reason:
  *
  * - `env` is not a runtime call at all. Values are resolved at finalize and
  *   travel in the config, so a worker reading `env` reaches nothing.
@@ -250,9 +420,17 @@ export const functionsDispatchCapabilitySchema = z.enum(FUNCTIONS_DISPATCH_CAPAB
  * touches the database, not how. Narrowing it would take per-statement analysis
  * we do not do, and guessing "read-only" from a declaration would be a grant
  * the author never asked for and cannot see.
+ *
+ * The three platform-service grants are named for the operation an author
+ * reaches for, and each covers its service's whole operation set for the same
+ * reason `db` widens: a declaration says a handler uses spam checking, not that
+ * it never files a correction.
  */
-export function functionsDispatchCapabilities(capabilities) {
-    const granted = new Set();
+export function functionsDispatchCapabilities(capabilities, platform = {}) {
+    // Storage is the durable, unversioned substrate every app receives. It is a
+    // base binding like the Zero client's `storage`, not a source-declared
+    // capability that disappears when a new version omits an import.
+    const granted = new Set(["storage.read", "storage.write"]);
     if (capabilities.db) {
         granted.add("db.read");
         granted.add("db.write");
@@ -263,14 +441,26 @@ export function functionsDispatchCapabilities(capabilities) {
     if (capabilities.logging) {
         granted.add("log");
     }
+    if (capabilities.gravatar) {
+        granted.add("gravatar.profile");
+    }
+    if (capabilities.spam) {
+        granted.add("spam.check");
+    }
+    if (capabilities.email) {
+        granted.add("email.send");
+    }
+    if (platform.nextCache) {
+        granted.add("next.cache");
+    }
     // Filtered from the canonical list so the order is stable: the grant is part
     // of the host's isolate identity, and a reordering would retire warm isolates
     // for no reason.
     return FUNCTIONS_DISPATCH_CAPABILITIES.filter((capability) => granted.has(capability));
 }
-/** Everything except `log` needs the relay to mean anything. */
+/** Logs and the host-local Next cache do not transit the origin relay. */
 export function functionsGrantNeedsRelay(granted) {
-    return granted.some((capability) => capability !== "log");
+    return granted.some((capability) => capability !== "log" && capability !== "next.cache");
 }
 /**
  * What the space origin needs in order to dispatch to the host on its own. The
@@ -295,6 +485,13 @@ export const functionsHostConfigSchema = z
      * single artifact.
      */
     bundleUrl: z.string().url(),
+    /**
+     * Where the host pulls the version's cache seed, minted beside the bundle
+     * URL for the same reasons — null exactly when the artifact carries no
+     * seed. The host folds it into the cache object's cold-start path, never
+     * into request serving: an unreachable seed is a cold cache, not an error.
+     */
+    seedUrl: z.string().url().nullable().default(null),
 })
     .strict();
 /**
@@ -321,6 +518,43 @@ export const functionsRelayConfigSchema = z
     maxConcurrentCalls: z.number().int().min(1).max(64),
 })
     .strict();
+/**
+ * Where the execution host reports how much this version ran.
+ *
+ * Absent means uncounted, not refused: a space whose configuration predates
+ * usage reporting must keep serving, and an execution tier that cannot reach
+ * the control plane must never fail a request over it. Counting is reporting
+ * only — nothing here throttles, and no limit is enforced anywhere from it.
+ */
+export const functionsUsageConfigSchema = z
+    .object({
+    url: z.string().url(),
+    /**
+     * Minted and verified by the control plane alone; the space only forwards
+     * it. Version-scoped like the relay credential, and folded into the host's
+     * isolate identity for the same reason: a rotated credential must not
+     * outlive its rotation inside a warm isolate.
+     */
+    token: z.string().min(1),
+})
+    .strict();
+/**
+ * The credential the execution host presents at the origin's purge route.
+ *
+ * Only the token lives here: the purge route is on whichever hostname the
+ * visitor actually hit, so the origin composes the URL from the request host at
+ * dispatch time — exactly as it does for log intake — instead of freezing one
+ * hostname at finalize. A third credential rather than a reuse of the relay's,
+ * for the relay's own reason: purging cached responses is a distinct authority,
+ * and a worker whose relay is unusable must still be able to invalidate what it
+ * rendered. Version-scoped and folded into the host's isolate identity like its
+ * siblings, so a republish revokes it.
+ */
+export const functionsPurgeConfigSchema = z
+    .object({
+    token: z.string().min(1),
+})
+    .strict();
 /**
  * What a build declares about its worker — everything the CLI can know from the
  * author's project alone.
@@ -349,15 +583,18 @@ export const functionsSourceFinalizeSchema = z
  * The document the control plane sends to the runtime, which the engine stores
  * beside the version's files and the origin reads on every dispatch.
  *
- * It is the build's declaration plus the four things only the platform can
- * supply: where to dispatch, what the worker is allowed to do, the credential
- * that lets it do those things, and the resolved values of its variables.
+ * It is the build's declaration plus the things only the platform can supply:
+ * where to dispatch, what the worker is allowed to do, the credentials that let
+ * it do those things and report what it did, and the resolved values of its
+ * variables.
  */
 export const functionsRuntimeConfigSchema = functionsSourceFinalizeSchema
     .extend({
     host: functionsHostConfigSchema,
-    grantedCapabilities: z.array(functionsDispatchCapabilitySchema).max(8).default([]),
+    grantedCapabilities: z.array(functionsDispatchCapabilitySchema).max(10).default([]),
     relay: functionsRelayConfigSchema.nullable().default(null),
+    usage: functionsUsageConfigSchema.nullable().default(null),
+    purge: functionsPurgeConfigSchema.nullable().default(null),
     /**
      * Resolved at finalize, so a worker reading configuration never calls back
      * to us for it — and so rotating a variable is a republish with an audit
@@ -392,10 +629,13 @@ export function createFunctionsSourceFinalize(input) {
             entry: input.entry,
             mainModule: input.mainModule,
             bundle: input.bundle,
+            seed: input.seed ?? null,
             compatibilityDate: input.compatibilityDate,
             compatibilityFlags: input.compatibilityFlags ?? [],
             routes: input.routes ?? [],
+            bypassCookies: input.bypassCookies ?? [],
             capabilities: input.capabilities ?? {},
+            platform: { nextCache: input.nextCache ?? false },
         },
         variables: {
             source: "spacefast-variables",
@@ -421,10 +661,12 @@ export const functionsExecutionStateSchema = z.enum([
     "serving",
 ]);
 /**
- * What a live worker is, as the `app` member of a space's runtime status.
+ * What a live worker is, as the `worker` member of a space's runtime status.
+ *
+ * It carries no kind tag. The member it rides in already says which product
+ * answered, and the same tree can carry a capsule beside it — a discriminant
+ * here could only repeat the field name or contradict its sibling.
  *
- * Shaped like `zeroAppSchema` and discriminated by the same `runtimeKind`, so a
- * reader switches on one field rather than probing for which product answered.
  * No `versionId`: the status response it rides in already names the live
  * version.
  *
@@ -435,7 +677,6 @@ export const functionsExecutionStateSchema = z.enum([
  */
 export const functionsAppSchema = z
     .object({
-    runtimeKind: z.literal(FUNCTIONS_RUNTIME_KIND),
     artifactId: z.string().min(1),
     appName: z.string().min(1),
     entry: z.string().min(1),
@@ -455,21 +696,3 @@ export const functionsAppSchema = z
         .strict(),
 })
     .strict();
-/**
- * The wire shape of the origin's log-read route, not a public API contract.
- *
- * Handler logs reach callers through `GET /v1/spaces/:spaceId/logs/runtime`,
- * which serves the platform's own `runtimeLogListResponseSchema` for both
- * execution tiers. These aliases describe the hop underneath it: a worker tails
- * its output to the origin that dispatched it, and the control plane reads it
- * back from there. Keeping them named after this product is the point — the
- * origin is the only place a wp.cloud-hosted space keeps anything, and Zero's
- * records never travel this path at all.
- */
-export const functionsLogEntrySchema = executionLogEntrySchema;
-export const functionsLogListQuerySchema = executionLogListQuerySchema;
-export const functionsLogListResponseSchema = executionLogListResponseSchema;
-/** Narrows a space's live runtime kind to this product. */
-export function isFunctionsRuntime(kind) {
-    return kind === FUNCTIONS_RUNTIME_KIND;
-}

package/dist/contracts/git.d.ts

@@ -8,8 +8,8 @@ export declare const buildTarget: z.ZodEnum<{
 export declare const buildTrigger: z.ZodEnum<{
     push: "push";
     manual: "manual";
-    pull_request: "pull_request";
     retry: "retry";
+    pull_request: "pull_request";
 }>;
 export declare const buildEnvironmentScopeValues: readonly ["runtime", "build", "build:production", "build:preview"];
 export declare const buildEnvironmentScope: z.ZodEnum<{
@@ -96,16 +96,16 @@ export declare const gitConnectionCreateSchema: z.ZodPipe<z.ZodObject<{
     autoDeployProduction: z.ZodDefault<z.ZodBoolean>;
     autoDeployPreviews: z.ZodDefault<z.ZodBoolean>;
     buildSettings: z.ZodOptional<z.ZodObject<{
-        rootDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        buildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        outputDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        ignoredBuildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        frameworkPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        platformPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        timeoutSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodTransform<{
     productionBranch: string;
@@ -163,16 +163,16 @@ export declare const gitConnectionPatchSchema: z.ZodObject<{
     autoDeployProduction: z.ZodOptional<z.ZodBoolean>;
     autoDeployPreviews: z.ZodOptional<z.ZodBoolean>;
     buildSettings: z.ZodOptional<z.ZodObject<{
-        rootDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        buildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        outputDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        ignoredBuildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        frameworkPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        platformPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        timeoutSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const gitConnectionAnalyzeSchema: z.ZodObject<{
@@ -249,7 +249,13 @@ export declare const githubInstallationSchema: z.ZodObject<{
     htmlUrl: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const githubInstallationsResponseSchema: z.ZodObject<{
-    appConfigured: z.ZodBoolean;
+    readiness: z.ZodObject<{
+        canAuthorize: z.ZodBoolean;
+        canInstall: z.ZodBoolean;
+        webhookReady: z.ZodBoolean;
+        codeStorageReady: z.ZodBoolean;
+        ready: z.ZodBoolean;
+    }, z.core.$strip>;
     installUrl: z.ZodNullable<z.ZodString>;
     installations: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -258,18 +264,6 @@ export declare const githubInstallationsResponseSchema: z.ZodObject<{
         htmlUrl: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const githubInstallationClaimSchema: z.ZodObject<{
-    installationId: z.ZodString;
-    state: z.ZodString;
-}, z.core.$strip>;
-export declare const githubInstallationClaimResponseSchema: z.ZodObject<{
-    installation: z.ZodObject<{
-        id: z.ZodString;
-        accountLogin: z.ZodString;
-        accountType: z.ZodNullable<z.ZodString>;
-        htmlUrl: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
 export declare const githubRepositorySchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;

package/dist/contracts/git.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { BuildSettingsSchema } from "./builds.js";
+import { BuildSettingsOverrideSchema, BuildSettingsSchema } from "./builds.js";
 import { gitProvider } from "./enums.js";
 const nullableString = z.string().trim().min(1).nullable();
 export const buildTargetValues = ["production", "preview"];
@@ -55,7 +55,7 @@ export const gitConnectionCreateSchema = z
     credential: z.string().trim().min(1).nullable().optional(),
     autoDeployProduction: z.boolean().default(true),
     autoDeployPreviews: z.boolean().default(true),
-    buildSettings: gitBuildSettingsSchema.partial().optional(),
+    buildSettings: BuildSettingsOverrideSchema.optional(),
 })
     .transform((value) => ({
     ...value,
@@ -67,7 +67,7 @@ export const gitConnectionPatchSchema = z.object({
     credential: z.string().trim().min(1).nullable().optional(),
     autoDeployProduction: z.boolean().optional(),
     autoDeployPreviews: z.boolean().optional(),
-    buildSettings: gitBuildSettingsSchema.partial().optional(),
+    buildSettings: BuildSettingsOverrideSchema.optional(),
 });
 export const gitConnectionAnalyzeSchema = z.object({
     ref: z.string().trim().min(1).optional(),
@@ -95,17 +95,16 @@ export const githubInstallationSchema = z.object({
     htmlUrl: z.string().url().nullable(),
 });
 export const githubInstallationsResponseSchema = z.object({
-    appConfigured: z.boolean(),
+    readiness: z.object({
+        canAuthorize: z.boolean(),
+        canInstall: z.boolean(),
+        webhookReady: z.boolean(),
+        codeStorageReady: z.boolean(),
+        ready: z.boolean(),
+    }),
     installUrl: z.string().url().nullable(),
     installations: z.array(githubInstallationSchema),
 });
-export const githubInstallationClaimSchema = z.object({
-    installationId: z.string().trim().min(1),
-    state: z.string().trim().min(1),
-});
-export const githubInstallationClaimResponseSchema = z.object({
-    installation: githubInstallationSchema,
-});
 export const githubRepositorySchema = z.object({
     id: z.string(),
     name: z.string(),

package/dist/contracts/grants.d.ts

@@ -8,15 +8,12 @@ export declare const grantCapabilitySchema: z.ZodEnum<{
     "access.manage": "access.manage";
 }>;
 export type GrantCapability = z.infer<typeof grantCapabilitySchema>;
-export declare const GRANT_CAPABILITY_PRESETS: readonly ["view", "comment", "publish", "manage"];
-export type GrantCapabilityPreset = (typeof GRANT_CAPABILITY_PRESETS)[number];
-export declare const GRANT_PRESET_CAPABILITIES: Record<GrantCapabilityPreset, GrantCapability[]>;
 export declare const GRANT_AUDIENCE_KINDS: readonly ["public", "team", "person", "link", "password", "machine", "external"];
 export declare const grantAudienceKindSchema: z.ZodEnum<{
     link: "link";
     team: "team";
-    external: "external";
     public: "public";
+    external: "external";
     person: "person";
     password: "password";
     machine: "machine";
@@ -427,8 +424,8 @@ export declare const grantCheckQuerySchema: z.ZodObject<{
     audience: z.ZodDefault<z.ZodEnum<{
         link: "link";
         team: "team";
-        external: "external";
         public: "public";
+        external: "external";
         person: "person";
         password: "password";
         machine: "machine";
@@ -1079,6 +1076,13 @@ export declare const identityConnectionPublicKeySchema: z.ZodObject<{
     publicKey: z.ZodString;
 }, z.core.$strict>;
 export type IdentityConnectionPublicKey = z.infer<typeof identityConnectionPublicKeySchema>;
+/**
+ * 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 declare const RESERVED_IDENTITY_CONNECTION_ISSUERS: readonly ["spacefast-membership", "claim-preview", "spacefast-owner"];
 export declare const identityConnectionCreateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"oidc">;
     name: z.ZodString;