@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/runtime-purge.js

@@ -0,0 +1,5 @@
+import { z } from "zod";
+// `queued` means the purge journal durably owns the work; the edge provider
+// call may not have run yet. `pending` is narrower: the synchronous worker kick
+// never reached the purge entrypoint, so maintenance still owes the attempt.
+export const runtimePurgeStatusSchema = z.enum(["queued", "ok", "failed", "pending"]);

package/dist/contracts/runtime-services.d.ts

@@ -2,30 +2,18 @@
  * Platform services that tenant code reaches through the runtime rather than
  * through a credential of its own: Gravatar, spam checking, and mail.
  *
- * Three properties hold for all three, and they are the reason this file
- * exists instead of three unrelated ones:
+ * Every call is brokered, so no credential is ever in tenant reach. Zero hands
+ * these to a handler as `ctx.gravatar` / `ctx.spam` / `ctx.email`; Functions
+ * binds them as `env.GRAVATAR` / `env.SPAM` / `env.EMAIL`, with the same method
+ * names and fields. Zero's `check` narrows the input because its HTTP host can
+ * add request metadata; a detached Functions call supplies it explicitly.
  *
- * - **The credential is never in tenant reach.** An Akismet key or a Gravatar
- *   token in a bundle is a published secret, and a wp.cloud `SMTP_PASS` in a
- *   capsule is worse. Every call below is brokered: the runtime attaches
- *   authority outside the code that asked for the call.
- * - **The interface is the contract, not the accessor.** Zero hands these to a
- *   handler as `ctx.gravatar` / `ctx.spam` / `ctx.email`; Functions binds them
- *   as `env.GRAVATAR` / `env.SPAM` / `env.EMAIL`. Method names and semantic
- *   fields stay shared. Zero's `check` narrows the input because its HTTP host
- *   can add request metadata; a detached Functions call supplies that metadata
- *   explicitly.
- * - **The client is the same source on both tiers.** See
- *   `RUNTIME_SERVICE_CLIENT_SOURCE`: normalization, validation and the pure
- *   avatar-URL construction are one implementation injected into both runtimes,
- *   so the two tiers cannot drift into behaving differently.
- *
- * What differs between tiers is the transport under `call()`, and only that.
+ * `RUNTIME_SERVICE_CLIENT_SOURCE` is one implementation injected into both
+ * runtimes, so only the transport under `call()` differs between tiers.
  */
 /**
- * What Gravatar serves when an address has no image. `404` is here so callers
- * can detect absence by status instead of receiving a generated face they then
- * have to recognise as a placeholder.
+ * What Gravatar serves when an address has no image. `404` lets a caller detect
+ * absence by status instead of by recognising a generated placeholder.
  */
 export declare const GRAVATAR_DEFAULTS: readonly ["404", "mp", "identicon", "monsterid", "wavatar", "retro", "robohash", "blank"];
 export type GravatarDefault = (typeof GRAVATAR_DEFAULTS)[number];
@@ -34,7 +22,7 @@ export type GravatarRating = (typeof GRAVATAR_RATINGS)[number];
 /** Gravatar's own ceiling. Larger values are refused rather than clamped. */
 export declare const GRAVATAR_AVATAR_MAX_SIZE = 2048;
 export type GravatarAvatarOptions = {
-    /** Requested square edge in pixels, 1–2048. */
+    /** Requested square edge in pixels, 1 to 2048. */
     size?: number;
     /** Image to serve when the address has no Gravatar. */
     default?: GravatarDefault;
@@ -49,9 +37,9 @@ export type GravatarVerifiedAccount = {
     label: string | null;
 };
 /**
- * The subset of the Gravatar profile that is stable, public, and useful to a
- * page. Deliberately not the raw upstream document: passing that through would
- * make every upstream field addition a silent contract change here.
+ * The stable, public subset of the Gravatar profile. Not the raw upstream
+ * document: passing that through would make every upstream field addition a
+ * silent contract change.
  */
 export type GravatarProfile = {
     hash: string;
@@ -64,32 +52,24 @@ export type GravatarProfile = {
     verifiedAccounts: GravatarVerifiedAccount[];
 };
 export type Gravatar = {
-    /**
-     * Pure and synchronous: an avatar URL is a hash and a query string, so it
-     * costs no network call and cannot fail. It stays on this interface anyway
-     * because an author looking for an avatar looks here, not in a utility
-     * module.
-     */
+    /** Pure and synchronous: an avatar URL is a hash and a query string. */
     avatarUrl(email: string, options?: GravatarAvatarOptions): string;
     /** The profile behind an address, or null when the address has none. */
     profile(email: string): Promise<GravatarProfile | null>;
 };
 /**
- * Akismet's recognised content types. The vendor is not in the name of
- * anything an author touches — `ctx.spam` outlives whichever service answers
- * it — but the vocabulary is Akismet's because the classifier is trained on
- * it, and inventing synonyms would only lose signal.
+ * Akismet's recognised content types. The vocabulary is Akismet's because the
+ * classifier is trained on it; the vendor name stays out of the API surface,
+ * because `ctx.spam` outlives whichever service answers it.
  */
 export declare const SPAM_CONTENT_TYPES: readonly ["comment", "reply", "forum-post", "contact-form", "signup", "message"];
 export type SpamContentType = (typeof SPAM_CONTENT_TYPES)[number];
 /**
  * One complete submission, as the classifier sees it. Detached runtimes such
- * as Functions use this shape; Zero uses {@link RequestSpamSubmission} while
- * handling an HTTP invocation and fills the network fields itself.
+ * as Functions use this shape; Zero uses {@link RequestSpamSubmission} and
+ * fills the network fields itself.
  *
- * `userIp` and `userAgent` are the two heaviest signals Akismet uses, and
- * accuracy drops sharply without them — hence `userIp` being required rather
- * than another optional field an author would skip.
+ * `userIp` is required because accuracy drops sharply without it.
  */
 export type SpamSubmission = {
     /** The text being classified. */
@@ -106,9 +86,7 @@ export type SpamSubmission = {
     authorUrl?: string;
     /**
      * Set to `"administrator"` for a trusted, authenticated operator of the
-     * space. Akismet passes that role unconditionally, so this is an author's
-     * own escape hatch for their own team — it grants nothing beyond skipping a
-     * check the author asked for.
+     * space. Akismet passes that role unconditionally, so the check is skipped.
      */
     authorRole?: "administrator";
     /** ISO-8601 UTC. Defaults to the moment of the call. */
@@ -119,19 +97,17 @@ export type SpamSubmission = {
 /**
  * A spam check made while handling a visitor request.
  *
- * Network evidence is deliberately absent. The runtime, not capsule code,
- * supplies the visitor IP, user agent, referrer, and current URL from the
- * trusted invocation envelope. This keeps a browser from claiming its own IP
- * through mutation arguments or an endpoint body.
+ * The runtime, not capsule code, supplies the visitor IP, user agent, referrer,
+ * and current URL from the trusted invocation envelope, so a browser cannot
+ * claim its own IP through mutation arguments or an endpoint body.
  */
 export type RequestSpamSubmission = Omit<SpamSubmission, "userIp" | "userAgent" | "referrer" | "permalink">;
 export type SpamVerdict = {
     /** Whether the submission classifies as spam. */
     spam: boolean;
     /**
-     * Blatant, pervasive spam. Akismet's own guidance is that this may be
-     * dropped outright rather than held for review, so it is surfaced instead of
-     * being folded into `spam`.
+     * Blatant, pervasive spam. Akismet's guidance is to drop it outright rather
+     * than hold it for review.
      */
     discard: boolean;
 };
@@ -157,10 +133,8 @@ export type RuntimeSpamRequestContext = {
     permalink?: string;
 };
 /**
- * The structured subset of Cloudflare's `SendEmail` binding, field for field.
- *
- * Matching it is a portability decision, not an aesthetic one: a worker
- * deployed straight to Cloudflare gets the native binding and the same
+ * The structured subset of Cloudflare's `SendEmail` binding, field for field: a
+ * worker deployed straight to Cloudflare gets the native binding, and the same
  * message-building code has to typecheck against both.
  */
 export type EmailAddress = {
@@ -180,40 +154,34 @@ export type EmailMessage = {
 };
 export type SendEmail = {
     /**
-     * Accepts one email effect. The identifier names the message; it is not a
-     * claim that anything was delivered, and no state beyond "queued" is
-     * observable from here — see the runtime's message views for that.
+     * Accepts one email effect. The identifier names the message, not a delivery;
+     * nothing beyond "queued" is observable here.
      */
     send(message: EmailMessage): Promise<{
         messageId: string;
     }>;
 };
 /**
- * The hosts a broker may reach on a tenant's behalf are deliberately NOT listed
- * here. That table lives in `stattic-runtime-core`'s egress policy, where it is
- * generated into both the runtime's PHP constants and the Rust broker, so one
- * declaration is enforced at both places a connection is actually made. A copy
- * in this file would be a third statement of the same fact that nothing checks.
+ * The hosts a broker may reach on a tenant's behalf are NOT listed here. That
+ * table lives in `stattic-runtime-core`'s egress policy, generated into both
+ * the runtime's PHP constants and the Rust broker.
  *
- * The `gravatar.com` in the avatar URL below is not that table: it is a public
- * URL handed to a browser, not an egress target.
+ * The `gravatar.com` in the avatar URL below is a public URL handed to a
+ * browser, not an egress target.
  */
 /**
  * The client both runtimes inject, as source.
  *
- * It is a string rather than a module because neither runtime can import from
- * npm at the point it needs this: Zero compiles a capsule to QuickJS bytecode
- * with a generated prelude, and the Functions host injects modules into a
- * tenant isolate it does not build. Shipping one source to both is what makes
- * "the same API" a fact about the code rather than a promise in a doc.
+ * A string rather than a module because neither runtime can import from npm
+ * here: Zero compiles a capsule to QuickJS bytecode with a generated prelude,
+ * and the Functions host injects modules into a tenant isolate it does not
+ * build.
  *
  * It closes over nothing of ours. The host defines `call(service, operation,
- * payload)` and everything else — normalization, the pure avatar URL, the
- * shapes returned to tenant code — is here, identical on both tiers.
+ * payload)`; everything else is here, identical on both tiers.
  *
- * The SHA-256 is hand-rolled for the same reason: QuickJS has no WebCrypto,
- * and Cloudflare's `crypto.subtle` is async, which would force `avatarUrl` to
- * return a promise on one tier and a string on the other. A synchronous
- * implementation is the only way the signature can be identical.
+ * The SHA-256 is hand-rolled because QuickJS has no WebCrypto and
+ * `crypto.subtle` is async, which would make `avatarUrl` return a promise on
+ * one tier and a string on the other.
  */
 export declare const RUNTIME_SERVICE_CLIENT_SOURCE: string;

package/dist/contracts/runtime-services.js

@@ -2,33 +2,21 @@
  * Platform services that tenant code reaches through the runtime rather than
  * through a credential of its own: Gravatar, spam checking, and mail.
  *
- * Three properties hold for all three, and they are the reason this file
- * exists instead of three unrelated ones:
+ * Every call is brokered, so no credential is ever in tenant reach. Zero hands
+ * these to a handler as `ctx.gravatar` / `ctx.spam` / `ctx.email`; Functions
+ * binds them as `env.GRAVATAR` / `env.SPAM` / `env.EMAIL`, with the same method
+ * names and fields. Zero's `check` narrows the input because its HTTP host can
+ * add request metadata; a detached Functions call supplies it explicitly.
  *
- * - **The credential is never in tenant reach.** An Akismet key or a Gravatar
- *   token in a bundle is a published secret, and a wp.cloud `SMTP_PASS` in a
- *   capsule is worse. Every call below is brokered: the runtime attaches
- *   authority outside the code that asked for the call.
- * - **The interface is the contract, not the accessor.** Zero hands these to a
- *   handler as `ctx.gravatar` / `ctx.spam` / `ctx.email`; Functions binds them
- *   as `env.GRAVATAR` / `env.SPAM` / `env.EMAIL`. Method names and semantic
- *   fields stay shared. Zero's `check` narrows the input because its HTTP host
- *   can add request metadata; a detached Functions call supplies that metadata
- *   explicitly.
- * - **The client is the same source on both tiers.** See
- *   `RUNTIME_SERVICE_CLIENT_SOURCE`: normalization, validation and the pure
- *   avatar-URL construction are one implementation injected into both runtimes,
- *   so the two tiers cannot drift into behaving differently.
- *
- * What differs between tiers is the transport under `call()`, and only that.
+ * `RUNTIME_SERVICE_CLIENT_SOURCE` is one implementation injected into both
+ * runtimes, so only the transport under `call()` differs between tiers.
  */
 /* -------------------------------------------------------------------------- */
 /* Gravatar                                                                    */
 /* -------------------------------------------------------------------------- */
 /**
- * What Gravatar serves when an address has no image. `404` is here so callers
- * can detect absence by status instead of receiving a generated face they then
- * have to recognise as a placeholder.
+ * What Gravatar serves when an address has no image. `404` lets a caller detect
+ * absence by status instead of by recognising a generated placeholder.
  */
 export const GRAVATAR_DEFAULTS = [
     "404",
@@ -47,10 +35,9 @@ export const GRAVATAR_AVATAR_MAX_SIZE = 2048;
 /* Spam                                                                        */
 /* -------------------------------------------------------------------------- */
 /**
- * Akismet's recognised content types. The vendor is not in the name of
- * anything an author touches — `ctx.spam` outlives whichever service answers
- * it — but the vocabulary is Akismet's because the classifier is trained on
- * it, and inventing synonyms would only lose signal.
+ * Akismet's recognised content types. The vocabulary is Akismet's because the
+ * classifier is trained on it; the vendor name stays out of the API surface,
+ * because `ctx.spam` outlives whichever service answers it.
  */
 export const SPAM_CONTENT_TYPES = [
     "comment",
@@ -64,14 +51,12 @@ export const SPAM_CONTENT_TYPES = [
 /* Upstreams                                                                   */
 /* -------------------------------------------------------------------------- */
 /**
- * The hosts a broker may reach on a tenant's behalf are deliberately NOT listed
- * here. That table lives in `stattic-runtime-core`'s egress policy, where it is
- * generated into both the runtime's PHP constants and the Rust broker, so one
- * declaration is enforced at both places a connection is actually made. A copy
- * in this file would be a third statement of the same fact that nothing checks.
+ * The hosts a broker may reach on a tenant's behalf are NOT listed here. That
+ * table lives in `stattic-runtime-core`'s egress policy, generated into both
+ * the runtime's PHP constants and the Rust broker.
  *
- * The `gravatar.com` in the avatar URL below is not that table: it is a public
- * URL handed to a browser, not an egress target.
+ * The `gravatar.com` in the avatar URL below is a public URL handed to a
+ * browser, not an egress target.
  */
 /* -------------------------------------------------------------------------- */
 /* The shared client                                                           */
@@ -79,20 +64,17 @@ export const SPAM_CONTENT_TYPES = [
 /**
  * The client both runtimes inject, as source.
  *
- * It is a string rather than a module because neither runtime can import from
- * npm at the point it needs this: Zero compiles a capsule to QuickJS bytecode
- * with a generated prelude, and the Functions host injects modules into a
- * tenant isolate it does not build. Shipping one source to both is what makes
- * "the same API" a fact about the code rather than a promise in a doc.
+ * A string rather than a module because neither runtime can import from npm
+ * here: Zero compiles a capsule to QuickJS bytecode with a generated prelude,
+ * and the Functions host injects modules into a tenant isolate it does not
+ * build.
  *
  * It closes over nothing of ours. The host defines `call(service, operation,
- * payload)` and everything else — normalization, the pure avatar URL, the
- * shapes returned to tenant code — is here, identical on both tiers.
+ * payload)`; everything else is here, identical on both tiers.
  *
- * The SHA-256 is hand-rolled for the same reason: QuickJS has no WebCrypto,
- * and Cloudflare's `crypto.subtle` is async, which would force `avatarUrl` to
- * return a promise on one tier and a string on the other. A synchronous
- * implementation is the only way the signature can be identical.
+ * The SHA-256 is hand-rolled because QuickJS has no WebCrypto and
+ * `crypto.subtle` is async, which would make `avatarUrl` return a promise on
+ * one tier and a string on the other.
  */
 export const RUNTIME_SERVICE_CLIENT_SOURCE = String.raw `
 const SERVICE_DEFAULTS = ${JSON.stringify(GRAVATAR_DEFAULTS)};
@@ -217,9 +199,8 @@ function sha256Hex(value) {
   return hex;
 }
 
-// Gravatar's own identifier rule. Trim and lower-case only: it deliberately
-// does not strip dots or plus-tags, because two addresses that differ there are
-// two accounts as far as Gravatar is concerned.
+// Gravatar's identifier rule: trim and lower-case only. Dots and plus-tags are
+// not stripped; two addresses that differ there are two Gravatar accounts.
 function gravatarHash(email) {
   if (typeof email !== "string" || email.trim() === "") {
     throw invalid("An email address is required.");
@@ -402,9 +383,8 @@ function emailPayload(message) {
     for (const name of Object.keys(message.headers)) {
       const value = message.headers[name];
       if (typeof value !== "string") throw invalid("Header " + name + " must be a string.");
-      // Refused here rather than at the broker so the author sees the field
-      // name they wrote. The broker refuses again — this is convenience, not
-      // the boundary.
+      // Refused here so the author sees the field name they wrote. The broker
+      // refuses again; this is convenience, not the boundary.
       if (/[^\x21-\x39\x3b-\x7e]/.test(name)) {
         throw invalid("Header " + name + " is not a valid header name.");
       }

package/dist/contracts/runtime-storage.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-/** Objects are addressed by a bare 128-bit random id — there is no key and no visibility. */
+/** Objects are addressed by a bare 128-bit random id. There is no key and no visibility. */
 export declare const runtimeStorageObjectIdSchema: z.ZodString;
 /** The runtime-scoped, revocable read key that makes a `/__stattic/u/<id>` URL readable. */
 export declare const runtimeStorageReadKeySchema: z.ZodString;
@@ -43,19 +43,19 @@ export declare const runtimeStorageListResponseSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type RuntimeStorageListResponse = z.infer<typeof runtimeStorageListResponseSchema>;
 export declare const runtimeStorageListPublicResponseSchema: z.ZodObject<{
-    data: z.ZodObject<{
-        objects: z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            contentType: z.ZodString;
-            createdAt: z.ZodString;
-            size: z.ZodNumber;
-            uploaderId: z.ZodString;
-            sha256: z.ZodString;
-            url: z.ZodString;
-        }, z.core.$strict>>;
-        cursor: z.ZodNullable<z.ZodString>;
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        contentType: z.ZodString;
+        createdAt: z.ZodString;
+        size: z.ZodNumber;
+        uploaderId: z.ZodString;
+        sha256: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strict>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
         hasMore: z.ZodBoolean;
-    }, z.core.$strict>;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const runtimeStorageDeleteResponseSchema: z.ZodObject<{
     id: z.ZodString;
@@ -97,7 +97,7 @@ export declare const runtimeStorageDeletePublicResponseSchema: 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";
             }>>>;
@@ -119,6 +119,7 @@ export declare const runtimeStorageReadKeyRotateResponseSchema: z.ZodObject<{
     purge: z.ZodObject<{
         status: z.ZodEnum<{
             failed: "failed";
+            queued: "queued";
             pending: "pending";
             ok: "ok";
         }>;

package/dist/contracts/runtime-storage.js

@@ -1,13 +1,25 @@
 import { z } from "zod";
-import { dataEnvelope, mutationEnvelope } from "./common.js";
-/** Objects are addressed by a bare 128-bit random id — there is no key and no visibility. */
+import { CursorPaginationSchema, mutationEnvelope } from "./common.js";
+import { runtimePurgeStatusSchema } from "./runtime-purge.js";
+/** Objects are addressed by a bare 128-bit random id. There is no key and no visibility. */
 export const runtimeStorageObjectIdSchema = z.string().regex(/^[a-f0-9]{32}$/);
 /** The runtime-scoped, revocable read key that makes a `/__stattic/u/<id>` URL readable. */
 export const runtimeStorageReadKeySchema = z.string().regex(/^[a-f0-9]{32}$/);
 export const runtimeStorageListQuerySchema = z
     .object({
-    cursor: z.string().min(1).max(2_048).optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z
+        .string()
+        .min(1)
+        .max(2_048)
+        .optional()
+        .describe("Opaque cursor from the previous page's `pagination.nextCursor`."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(50)
+        .describe("Maximum objects to return."),
 })
     .strict();
 export const runtimeStorageObjectSchema = z
@@ -18,12 +30,15 @@ export const runtimeStorageObjectSchema = z
     size: z.number().int().nonnegative(),
     uploaderId: z.string().min(1).max(255),
     sha256: z.string().regex(/^[a-f0-9]{64}$/),
-    // Path-relative and composed from the read key that was current at response
-    // time: `/__stattic/u/<id>?k=<key>`. The caller absolutizes it against
-    // whichever of the space's hostnames it is presenting.
+    // Path-relative, carrying the read key current at response time:
+    // `/__stattic/u/<id>?k=<key>`. The caller absolutizes it against whichever
+    // of the space's hostnames it is presenting.
     url: z.string().min(1),
 })
     .strict();
+// The runtime's own wire shape for a storage page, which the control plane
+// reads and then re-envelopes. `cursor`/`hasMore` here are the runtime's
+// spelling; the public route below answers the one platform list envelope.
 export const runtimeStorageListResponseSchema = z
     .object({
     objects: z.array(runtimeStorageObjectSchema),
@@ -31,7 +46,10 @@ export const runtimeStorageListResponseSchema = z
     hasMore: z.boolean(),
 })
     .strict();
-export const runtimeStorageListPublicResponseSchema = dataEnvelope(runtimeStorageListResponseSchema);
+export const runtimeStorageListPublicResponseSchema = z.object({
+    data: z.array(runtimeStorageObjectSchema),
+    pagination: CursorPaginationSchema,
+});
 export const runtimeStorageDeleteResponseSchema = z
     .object({
     id: runtimeStorageObjectIdSchema,
@@ -42,18 +60,16 @@ export const runtimeStorageDeletePublicResponseSchema = mutationEnvelope(runtime
 export const runtimeStorageReadKeyResponseSchema = z
     .object({ key: runtimeStorageReadKeySchema })
     .strict();
-// Rotation is the emergency lever: every URL minted under the old key answers
-// 404 afterwards, so the runtime purges every hostname on the box and reports
-// how that purge landed.
+// Every URL minted under the old key answers 404 after rotation, so the runtime
+// purges every hostname on the box and reports how that purge landed.
 export const runtimeStorageReadKeyRotateResponseSchema = z
     .object({
     key: runtimeStorageReadKeySchema,
     rotatedAt: z.string().datetime({ offset: true }),
-    // `none` is the receipt for a runtime that serves no hostname yet, so there
-    // was nothing to purge.
+    // `none`: the runtime serves no hostname yet, so there was nothing to purge.
     purge: z
         .object({
-        status: z.enum(["ok", "failed", "pending"]),
+        status: runtimePurgeStatusSchema,
         mode: z.enum(["urls", "domain", "none"]),
         urls: z.number().int().nonnegative().optional(),
     })

package/dist/contracts/sf-config-v1.d.ts

@@ -4,10 +4,29 @@ export declare const SF_CONFIG_V1_FILES: readonly ["sf.jsonc", "spacefast.jsonc"
 /** Published JSON Schema URL for the strict `sf.jsonc` v1 contract. */
 export declare const SF_CONFIG_V1_SCHEMA_URL: `${string}/schemas/sf.v1.json`;
 /**
- * How a redirect answers. Omitting it means 302. There is no 200: a rule that
- * serves other content under the requested URL is a `rewrites` entry.
+ * How a redirect answers. Omitting it means 302. There is no 200 and no 404:
+ * a rule that serves other content under the requested URL is a `rewrites`
+ * entry, with `notFound: true` when it should answer 404.
  */
 export type SfConfigV1RedirectStatus = 301 | 302 | 303 | 307 | 308;
+/**
+ * Query parameters a redirect or rewrite requires, as parameter name to
+ * capture name. `{ id: "id" }` is the `id=:id` token of a `_redirects` line.
+ */
+export type SfConfigV1QueryMatch = Record<string, string>;
+/**
+ * One header operation: `{ key, value }` sets, `{ key, remove: true }` is the
+ * `!Name` line of a `_headers` block. A remove entry carries no value.
+ */
+export type SfConfigV1HeaderEntry = {
+    key: string;
+    value: string;
+    remove?: never;
+} | {
+    key: string;
+    remove: true;
+    value?: never;
+};
 export type SfConfigV1 = {
     $schema?: typeof SF_CONFIG_V1_SCHEMA_URL;
     version: 1;
@@ -32,29 +51,35 @@ export type SfConfigV1 = {
         source: string;
         destination: string;
         status?: SfConfigV1RedirectStatus;
+        /** Answer even when the request path resolves to a committed file, the `!` of a `_redirects` rule. */
+        force?: boolean;
+        query?: SfConfigV1QueryMatch;
     }[];
     /**
      * Rewrite and proxy rules: the URL stays, the content comes from the
-     * destination. A path destination rewrites, an absolute URL proxies — the
-     * same 200 rules `_redirects` writes as `/from /to 200`, which is why they
-     * carry no status of their own.
+     * destination. A path destination rewrites, an absolute URL proxies. Both are
+     * the `/from /to 200` rule of `_redirects`, so they carry no status of their
+     * own. `notFound: true` answers 404 instead, and then the destination must be
+     * a path.
      */
     rewrites?: {
         source: string;
         destination: string;
         /** Let shared caches store the proxy response. Absolute-URL destinations only. */
         cache?: "shared";
+        /** Rewrite even when the request path resolves to a committed file, the `!` of a `200!` / `404!` file rule. */
+        force?: boolean;
+        query?: SfConfigV1QueryMatch;
+        notFound?: boolean;
     }[];
     /**
-     * Response headers to set on matching requests. Headers are a list, not a
-     * map, so repeated names (Set-Cookie) survive.
+     * Response headers to set or remove on matching requests. Headers are a
+     * list, not a map, so repeated names (Set-Cookie) survive and operations
+     * keep their order.
      */
     headers?: {
         source: string;
-        headers: {
-            key: string;
-            value: string;
-        }[];
+        headers: SfConfigV1HeaderEntry[];
     }[];
     metadata?: {
         title?: string;
@@ -67,6 +92,15 @@ export type SfConfigV1 = {
     access?: {
         public: string[];
     };
+    /**
+     * Scheduled requests against this space's own paths. The compiled
+     * `__spacefast/crons.json` derives each entry's key from its path; the
+     * schedule is never normalized.
+     */
+    crons?: {
+        path: string;
+        schedule: string;
+    }[];
 };
 export type EffectiveConfigV1 = {
     version: 1;
@@ -88,15 +122,15 @@ export type EffectiveConfigV1 = {
     headers?: SfConfigV1["headers"];
     metadata?: SfConfigV1["metadata"];
     substitute?: SfConfigV1["substitute"];
+    crons?: SfConfigV1["crons"];
     grants?: Grant[];
 };
 /**
  * Config-shape problems use the `config_*` codes; a bad routing rule reports
- * the same code the `_redirects` / `_headers` compiler would give it, because
- * it is the same grammar and the same compiler.
+ * the same code the `_redirects` / `_headers` compiler would give it.
  */
 export type SfConfigV1Issue = {
-    code: "config_alias" | "config_conflict" | "config_identity_moved" | "config_invalid" | "config_key_removed" | "config_unknown_key" | "header_basic_auth_unsupported" | "header_cache_control_platform_managed" | "header_cdn_cache_unsupported" | "header_name_invalid" | "header_name_unsupported" | "header_path_invalid" | "header_pattern_invalid" | "header_port_unsupported" | "header_value_invalid" | "redirect_cache_directive_invalid" | "redirect_cache_not_proxy" | "redirect_destination_invalid" | "redirect_destination_missing" | "redirect_host_invalid" | "redirect_loop_invalid" | "redirect_pattern_invalid" | "redirect_rewrite_destination_invalid" | "redirect_source_invalid" | "redirect_status_unsupported" | "redirect_status_use_rewrites" | "serve_index_required" | "template_syntax_retired";
+    code: "config_alias" | "config_conflict" | "config_cron_duplicate_path" | "config_cron_invalid_path" | "config_cron_invalid_schedule" | "config_cron_too_many" | "config_identity_moved" | "config_invalid" | "config_key_removed" | "config_unknown_key" | "header_basic_auth_unsupported" | "header_cache_control_platform_managed" | "header_cdn_cache_unsupported" | "header_name_invalid" | "header_name_unsupported" | "header_path_invalid" | "header_pattern_invalid" | "header_port_unsupported" | "header_value_invalid" | "redirect_cache_directive_invalid" | "redirect_cache_not_proxy" | "redirect_destination_invalid" | "redirect_destination_missing" | "redirect_host_invalid" | "redirect_loop_invalid" | "redirect_pattern_invalid" | "redirect_query_match_invalid" | "redirect_rewrite_destination_invalid" | "redirect_source_invalid" | "redirect_status_unsupported" | "redirect_status_use_rewrites" | "serve_index_required" | "template_syntax_retired";
     severity: "error" | "warning";
     path: string;
     line: number;

package/dist/contracts/slugs.js

@@ -2,10 +2,19 @@ import { z } from "zod";
 export const slugResourceKindValues = ["team", "space"];
 export const slugResourceKind = z.enum(slugResourceKindValues);
 export const slugAvailabilityQuerySchema = z.object({
-    kind: slugResourceKind,
-    slug: z.string().default(""),
-    currentSlug: z.string().optional(),
-    teamId: z.string().optional(),
+    kind: slugResourceKind.describe("Which kind of slug to check: a space slug or a team slug."),
+    slug: z
+        .string()
+        .default("")
+        .describe("Slug to check. It is normalized first, and the verdict describes the normalized form."),
+    currentSlug: z
+        .string()
+        .optional()
+        .describe("The resource's current slug, when renaming. A slug that normalizes to this one stays available instead of colliding with itself."),
+    teamId: z
+        .string()
+        .optional()
+        .describe("Team the space would belong to. Space slugs and their managed hostnames are checked inside that team; ignored for `kind=team`."),
 });
 export const slugAvailabilityResponseSchema = z.object({
     kind: slugResourceKind.describe("Resource kind the slug was checked for."),