@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/runtime-db.js

@@ -1,22 +1,43 @@
 import { z } from "zod";
-import { dataEnvelope, mutationEnvelope } from "./common.js";
+import { CursorPaginationSchema, dataEnvelope, mutationEnvelope } from "./common.js";
 import { executionIdentifierSchema, executionSha256Schema } from "./execution.js";
 import { ZERO_RUNTIME_KIND, zeroMigrationOperationSchema, zeroTableSchema } from "./zero.js";
 /**
  * The database surface, for whichever runtime a space is carrying.
  *
- * There is one database per space — the site's own MySQL — and at most one
- * runtime with a claim on it, so these contracts are runtime-neutral by
- * default. The two exceptions are stated explicitly: a migration plan is a
- * capsule's declaration and no worker has one, and the console hand-off is a
- * property of the wp.cloud site rather than of anything a version declared.
+ * One database per space, the site's own MySQL, and at most one runtime with a
+ * claim on it, so these contracts are runtime-neutral. Two exceptions: a
+ * migration plan is a capsule's declaration and no worker has one, and the
+ * console hand-off is a property of the wp.cloud site.
  *
- * The reads answer in the capsule's declaration shapes (`zeroTableSchema`,
- * `zeroMigrationOperationSchema`) because a capsule's declared schema is the
- * richest answer either runtime can give and a worker's is the same answer with
- * the declaration-shaped fields empty. Those shapes stay Zero-named and stay in
- * `./zero.js`: a declared table is the capsule's own statement about itself.
+ * Reads answer in the capsule's declaration shapes (`zeroTableSchema`,
+ * `zeroMigrationOperationSchema`); a worker's answer is the same shape with the
+ * declaration-shaped fields empty.
  */
+/**
+ * Whether the live version's declared migration plan has actually run against
+ * the space database. `applied` compares the recorded application against the
+ * plan's target `schemaHash`; it is `null` when no application record exists —
+ * a version finalized before this record existed, or a finalize whose ready
+ * receipt was a replay — because the control plane then cannot prove the plan
+ * ran. Honest unknown, never a guess.
+ */
+export const runtimeDbPlanStateSchema = z
+    .object({
+    applied: z
+        .boolean()
+        .nullable()
+        .describe("Whether this plan has been run against the space database. `null` when the control plane has no application record and cannot truthfully say."),
+    appliedSchemaHash: executionSha256Schema
+        .nullable()
+        .describe("Schema hash recorded when a plan was last applied for this version, if any."),
+    pendingOperationCount: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Queued or running `db migrate` operations for this space. Non-zero means an apply is still waiting."),
+})
+    .strict();
 export const runtimeDbInspectResponseSchema = z
     .object({
     versionId: z.string().min(1).nullable(),
@@ -26,19 +47,31 @@ export const runtimeDbInspectResponseSchema = z
     schemaHash: executionSha256Schema.nullable(),
     tables: z.array(zeroTableSchema).default([]),
     migrations: z.array(zeroMigrationOperationSchema).default([]),
+    plan: runtimeDbPlanStateSchema
+        .nullable()
+        .describe("Applied-state of the live version's migration plan. `null` when the live version declares no migration plan."),
 })
     .strict();
 export const runtimeDbInspectPublicResponseSchema = dataEnvelope(runtimeDbInspectResponseSchema);
 export const runtimeDbDumpQuerySchema = z
     .object({
-    table: executionIdentifierSchema.optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(25),
+    table: executionIdentifierSchema
+        .optional()
+        .describe("Dump only this declared table. Omit it to dump every declared table."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(25)
+        .describe("Maximum rows to read per table."),
 })
     .strict();
+export const runtimeDbCellValueSchema = z.json();
 export const runtimeDbDumpTableSchema = z
     .object({
     name: executionIdentifierSchema,
-    rows: z.array(z.record(z.string(), z.unknown())).default([]),
+    rows: z.array(z.record(z.string(), runtimeDbCellValueSchema)).default([]),
 })
     .strict();
 export const runtimeDbDumpResponseSchema = z
@@ -49,7 +82,22 @@ export const runtimeDbDumpResponseSchema = z
     tables: z.array(runtimeDbDumpTableSchema).default([]),
 })
     .strict();
-export const runtimeDbDumpPublicResponseSchema = dataEnvelope(runtimeDbDumpResponseSchema);
+// OpenAPI embeds a local recursive `$ref` below the route and cannot resolve
+// it, so the same wire contract is spelled out non-recursively here.
+const runtimeDbWireCellValueSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(z.unknown()),
+    z.record(z.string(), z.unknown()),
+]);
+const runtimeDbDumpPublicTableSchema = runtimeDbDumpTableSchema.extend({
+    rows: z.array(z.record(z.string(), runtimeDbWireCellValueSchema)).default([]),
+});
+export const runtimeDbDumpPublicResponseSchema = dataEnvelope(runtimeDbDumpResponseSchema.extend({
+    tables: z.array(runtimeDbDumpPublicTableSchema).default([]),
+}));
 export const runtimeDbExportOrderingSchema = z
     .object({
     tables: z.literal("name_asc"),
@@ -69,18 +117,35 @@ export const runtimeDbExportMetadataSchema = z
 export const runtimeDbExportMetadataPublicResponseSchema = dataEnvelope(runtimeDbExportMetadataSchema);
 export const runtimeDbExportPageQuerySchema = z
     .object({
-    schemaHash: executionSha256Schema,
-    cursor: z.string().min(1).max(4_096).optional(),
-    limit: z.coerce.number().int().min(1).max(1_000).default(500),
+    schemaHash: executionSha256Schema.describe("Schema fence from `GET /v1/spaces/{spaceId}/db/export`. A page whose table has changed shape since is rejected rather than mixed into the export."),
+    cursor: z
+        .string()
+        .min(1)
+        .max(4_096)
+        .optional()
+        .describe("Opaque cursor from the previous page's `pagination.nextCursor`."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(1_000)
+        .default(500)
+        .describe("Maximum rows to return in this page."),
 })
     .strict();
+// The runtime's own wire shape for an export page: rows plus a bare keyset
+// `cursor` that is null at the end. The control plane re-envelopes it into the
+// one platform list envelope below.
 export const runtimeDbExportPageSchema = z
     .object({
-    rows: z.array(z.record(z.string(), z.unknown())),
+    rows: z.array(z.record(z.string(), runtimeDbCellValueSchema)),
     cursor: z.string().nullable(),
 })
     .strict();
-export const runtimeDbExportPagePublicResponseSchema = dataEnvelope(runtimeDbExportPageSchema);
+export const runtimeDbExportPagePublicResponseSchema = z.object({
+    data: z.array(z.record(z.string(), runtimeDbWireCellValueSchema)),
+    pagination: CursorPaginationSchema,
+});
 export const runtimeDbMigrateResultSchema = z
     .object({
     versionId: z.string().min(1).describe("Live version whose migration plan this is."),

package/dist/contracts/runtime-purge.js

@@ -1,7 +1,5 @@
 import { z } from "zod";
-// One vocabulary for every runtime mutation that can invalidate edge state.
-// `queued` is a successful durable handoff: production FPM flushes the
-// management response once the purge journal owns the work, before the edge
-// provider call runs. `pending` is narrower — the synchronous worker kick did
-// not reach the purge entrypoint, so maintenance still owes the attempt.
+// `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;
@@ -90,8 +90,8 @@ export declare const runtimeStorageDeletePublicResponseSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/contracts/runtime-storage.js

@@ -1,14 +1,25 @@
 import { z } from "zod";
-import { dataEnvelope, mutationEnvelope } from "./common.js";
+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. */
+/** 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
@@ -19,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),
@@ -32,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,
@@ -43,15 +60,13 @@ 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: runtimePurgeStatusSchema,