@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/runtime-api.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
+import { CONTENT_SNIFF_KINDS } from "../utils/content-type.js";
 import { accessFenceKindSchema } from "./access.js";
 import { functionsRuntimeConfigSchema } from "./functions.js";
 import { grantSchema } from "./grants.js";
 import { manifestFileSchema } from "./internal.js";
 import { runtimePagesSchema } from "./pages.js";
+import { runtimePurgeStatusSchema } from "./runtime-purge.js";
 import { SPACE_CONFIG_CAPS } from "./space-config.js";
 import { zeroEndpointSchema, zeroRuntimeConfigSchema } from "./zero.js";
 const hostCanonicalRedirectSchema = z.object({
@@ -37,24 +39,20 @@ const previousVersionIdSchema = z
     .string()
     .min(1)
     .optional()
-    .describe("The pointer target this activation replaces (diff baseline).");
+    .describe("The previous live version used as the catalog diff baseline.");
 export const runtimePurgeReceiptSchema = z.object({
-    status: z.enum(["ok", "failed", "pending"]),
+    status: runtimePurgeStatusSchema,
     mode: z.enum(["urls", "domain"]),
     urls: z.number().int().nonnegative().optional(),
 });
-const runtimeMutationPurgeShape = {
+const runtimeMutationPurgeFields = {
     purge: runtimePurgeReceiptSchema.optional(),
 };
-export const runtimeSpacePurgeRequestSchema = z.object({
-    urls: z.array(z.string().startsWith("/")).optional(),
-});
 export const runtimeSpacePurgeResponseSchema = z.object({
     space_id: z.string().min(1),
     purge: runtimePurgeReceiptSchema,
 });
-// One bounded page of a version's file catalog — the runtime's own answer to
-// "which files does this version have". `view=source` is the uploaded,
+// One bounded page of a version's file catalog. `view=source` is the uploaded,
 // pre-substitution object; `view=served` is the immutable byte a visitor
 // receives, and `variant_route` marks a channel's substituted bytes within it.
 export const runtimeVersionFilesResponseSchema = z.object({
@@ -71,20 +69,37 @@ export const runtimeVersionFilesResponseSchema = z.object({
     })),
     next_cursor: z.string().min(1).nullable().optional(),
 });
+export const runtimeRetentionModeSchema = z.enum(["all", "list", "none"]);
 export const runtimeVersionCreateRequestSchema = z.object({
     version_id: z.string().min(1).optional(),
     files: z.array(manifestFileSchema),
-    // Retention is expressed as "everything from `reusable_version_id`": naming
-    // the base and NO list is the retain-all signal, which the runtime
-    // materializes from that version's own catalog at finalize (under the space
-    // lock). An explicit list is the narrower form — it retains exactly these
-    // paths — and is what a publish that prunes the base uses.
+    // Retention is stated, never inferred. `all` carries every path of
+    // `reusable_version_id` forward, materialized from the base catalog at
+    // finalize under the space lock, which keeps the lazy publish path free of a
+    // pre-upload round trip. `list` retains exactly `retained_files`, and an EMPTY
+    // list is meaningful: it drops every path the base held. `none` retains
+    // nothing.
+    //
+    // `all` and `list` both require `reusable_version_id`; only `list` may carry
+    // `retained_files`. The runtime has no delete list, so deletion IS omission
+    // from the retained set.
+    retention: runtimeRetentionModeSchema,
     retained_files: z.array(manifestFileSchema).optional(),
     reusable_version_id: z.string().min(1).optional(),
     manifest_hash: z.string().optional(),
     expires_at: z.string().optional(),
     metadata: z.record(z.string(), z.unknown()).default({}),
 });
+export const runtimeStaticZipIngestResponseSchema = z.object({
+    space_id: z.string().min(1),
+    files: z.array(z.object({
+        path: z.string().min(1),
+        size: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        sniff: z.enum(CONTENT_SNIFF_KINDS),
+    })),
+    pin_expires_at: z.string().datetime({ offset: true }),
+});
 export const runtimeVersionCreateResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
@@ -98,14 +113,26 @@ export const runtimeUploadSessionDescriptorSchema = z.object({
     expires_at: z.string(),
     manifest_hash: z.string().optional(),
     files: z.array(manifestFileSchema),
-    // Retained files only travel in the authenticated finalize request: they are
-    // unbounded and unused while accepting a PUT. Omitting them beside a
-    // `reusable_version_id` is the retain-all signal (see the create request),
-    // which is also what keeps a lazy session's descriptor inside its JWT budget.
+    // Retained files travel only in the authenticated finalize request: they are
+    // unbounded and unused while accepting a PUT, which keeps a lazy session's
+    // descriptor inside its JWT budget.
+    retention: runtimeRetentionModeSchema,
     retained_files: z.array(manifestFileSchema).optional(),
     reusable_version_id: z.string().min(1).optional(),
     metadata: z.record(z.string(), z.unknown()).default({}),
 });
+/**
+ * The retention half of a create-version body or session descriptor.
+ * `retained_files` is omitted when empty; with an explicit `retention` that
+ * omission means retain nothing beyond what `all` materializes.
+ */
+export function runtimeRetentionFields(input) {
+    return {
+        retention: input.retention,
+        ...(input.retainedFiles.length > 0 ? { retained_files: [...input.retainedFiles] } : {}),
+        ...(input.reusableVersionId ? { reusable_version_id: input.reusableVersionId } : {}),
+    };
+}
 export const RUNTIME_UPLOAD_SESSION_DESCRIPTOR_MAX_BYTES = 4096;
 // Hard wire budget for the complete `Authorization: Bearer <jwt>\r\n` line sent
 // on every PUT. Lazy-session selection measures the signed line and falls back
@@ -198,9 +225,9 @@ export const runtimeAuthorizationProjectionSchema = z
 // The space-level Comments projection the runtime serves as the whole answer
 // for `/__spacefast/comments/config`; the runtime adds only per-request fields.
 const runtimeSdkCommentsSchema = z.object({
-    // Comments boot on the live/published host.
+    // Which hosts Comments boot on: the live/published host, and the immutable
+    // version (preview) host.
     live: z.boolean(),
-    // ...and on an immutable version (preview) host.
     preview: z.boolean(),
     // Null before the Space has ever published.
     live_url: z.string().url().max(2000).nullable(),
@@ -409,17 +436,17 @@ const runtimeSubstitutionChannelSchema = z.object({
 export const runtimeVersionFinalizeRequestSchema = z.object({
     upload_id: z.string().min(1),
     session: runtimeUploadSessionDescriptorSchema.optional(),
+    // Capsule versions finalize and activate in separate calls, but still need
+    // the same publish delta as the combined path.
+    previous_version_id: previousVersionIdSchema,
     zero: zeroRuntimeConfigSchema.optional(),
     // Dispatch configuration for a Functions version. Absent for static versions,
-    // and absent when no execution host is configured — the version then serves
-    // as pure static content, because this config is what makes the origin
-    // dispatch at all.
+    // and absent when no execution host is configured; this config is what makes
+    // the origin dispatch at all.
     functions: functionsRuntimeConfigSchema.optional(),
-    // Variable resolution is the control plane's half of substitution and stays
-    // there: scopes come from its database, secret values are never decrypted for
-    // it, and `SPACEFAST_*` names are platform-provided. The finalizer owns the
-    // substitution itself — it has the staged bytes and the config that declares
-    // which paths are templates, so nothing pre-substituted crosses this wire.
+    // The control plane resolves variable scopes; secret values are never
+    // decrypted for it. The finalizer performs the substitution itself, so
+    // nothing pre-substituted crosses this wire.
     variable_scopes: z.array(runtimeVariableScopeSchema).optional(),
     system_variables: z.record(z.string().min(1), z.string()).optional(),
     // The space's channels, so the finalizer can compile each one's variant files
@@ -444,11 +471,9 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
         noindexHost: z.boolean().optional(),
         config: runtimeServingConfigSchema.optional(),
         // Origins the platform's own browser code loads from, keyed by the CSP
-        // directive each belongs in. Which origins those are is a control-plane
-        // decision — they come from its environment and are validated against the
-        // host this version will serve from — while the merge itself belongs to
-        // the finalizer, which is the only side that sees every CSP the version
-        // sets, in `_headers` and in config rules alike.
+        // directive each belongs in. The control plane picks them, validated
+        // against the host this version will serve from; the finalizer merges
+        // them, because only it sees every CSP the version sets.
         platform_csp_sources: z
             .record(z.string().min(1).max(64), z.array(z.string().min(1).max(512)).max(16))
             .optional(),
@@ -507,9 +532,8 @@ export const runtimeCatalogDeltaSchema = z.object({
 });
 // One compiled diagnostic from the finalizer. `path` is the committed file it
 // points at, carrying `file:line` when the compiler knew a line; `details` is
-// what it points at INSIDE that file — the variable, the channel, the colliding
-// routes — which is the difference between a publish failure you can act on and
-// one you can only retry.
+// what it points at INSIDE that file: the variable, the channel, or the
+// colliding routes.
 export const runtimeCompileDiagnosticSchema = z.object({
     severity: z.enum(["info", "warning", "error"]),
     code: z.string().min(1),
@@ -517,6 +541,31 @@ export const runtimeCompileDiagnosticSchema = z.object({
     path: z.string().optional(),
     details: z.record(z.string(), z.unknown()).optional(),
 });
+export const runtimeRouteInventorySchema = z.object({
+    format: z.literal("stattic.route-inventory.v1"),
+    routes: z.array(z.object({
+        id: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+        kind: z.enum([
+            "redirect",
+            "rewrite",
+            "proxy",
+            "not-found",
+            "functions",
+            "php-function",
+            "zero-control",
+            "zero-endpoint",
+        ]),
+        source: z.string().min(1),
+        runtime: z.enum(["routing", "cloudflare-worker", "php", "quick-js"]),
+        host: z.string().min(1),
+        path: z.string().startsWith("/"),
+        methods: z.array(z.string().min(1)).min(1),
+        auth: z.literal("inherit"),
+        cache: z.literal("shared").optional(),
+        destination: z.string().min(1).optional(),
+        status: z.number().int().min(200).max(599).optional(),
+    })),
+});
 // What the version's conventions and config compiled TO. The counts are the
 // control plane's version-row projection; `proxy_rules` is what it overlays the
 // publishing team's plan onto, because the compiled artifact never bakes a plan
@@ -530,16 +579,41 @@ export const runtimeCompiledRoutingSchema = z.object({
         .max(1000)
         .default([]),
 });
+// What one finalize RUN cost, stage by stage, straight off the native
+// finalizer's envelope, which is why these keys are camelCase while the rest of
+// this receipt is not. `skippedFiles` is the incrementality gauge: it stays 0
+// while every finalize rebuilds everything.
+export const runtimeFinalizeTelemetrySchema = z.object({
+    stagedFiles: z.number().int().nonnegative(),
+    generatedFiles: z.number().int().nonnegative(),
+    decoratedFiles: z.number().int().nonnegative(),
+    skippedFiles: z.number().int().nonnegative(),
+    stagingMs: z.number().int().nonnegative(),
+    templateSubstitutionMs: z.number().int().nonnegative(),
+    htmlPipelineMs: z.number().int().nonnegative(),
+    // The four stages below ship with the finalizer that splits them out; an
+    // engine predating the split reports the coarser stages only.
+    conventionsMs: z.number().int().nonnegative().optional(),
+    zeroCompileMs: z.number().int().nonnegative().optional(),
+    blobInstallMs: z.number().int().nonnegative(),
+    listingsMs: z.number().int().nonnegative().optional(),
+    responseTablesMs: z.number().int().nonnegative(),
+    catalogDeltaMs: z.number().int().nonnegative(),
+    artifactsWriteMs: z.number().int().nonnegative().optional(),
+    totalMs: z.number().int().nonnegative(),
+});
 export const runtimeVersionFinalizeResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
     status: z.literal("ready"),
     zero_endpoint_count: z.number().int().nonnegative().optional(),
-    // The finalizer is the one conventions/config compiler, so what it compiled is
-    // reported back rather than recomputed: the control plane runs no second
-    // compile pass to learn its own version row.
+    // The finalizer is the one conventions/config compiler, so the control plane
+    // runs no second compile pass to learn its own version row.
     diagnostics: z.array(runtimeCompileDiagnosticSchema).default([]),
     routing: runtimeCompiledRoutingSchema.optional(),
+    // Versioned, finalizer-owned route declarations. Optional while runtimes
+    // finalized before the inventory ships remain replayable.
+    route_inventory: runtimeRouteInventorySchema.optional(),
     // Provenance for the substitution the finalizer performed: dependency name
     // (`NAME` or `NAME@channel`) -> SHA-256 of the value it resolved to. This is
     // what answers "does changing this variable require a republish?".
@@ -556,12 +630,15 @@ export const runtimeVersionFinalizeResponseSchema = z.object({
     // the catalog at finalize. Null when the version serves no image.
     preview_image_path: z.string().min(1).nullable().optional(),
     readiness_target: runtimeReadinessTargetSchema,
+    // Absent whenever the runtime answered without finalizing: a replayed or
+    // idempotent finalize re-runs no stage and reports no timings.
+    telemetry: runtimeFinalizeTelemetrySchema.optional(),
     activation_event_id: z
         .string()
         .min(1)
         .optional()
         .describe("Stable route_updated event id when finalize also activated a route."),
-    ...runtimeMutationPurgeShape,
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeZeroMigrationsApplyResponseSchema = z.object({
     space_id: z.string(),
@@ -571,9 +648,10 @@ export const runtimeZeroMigrationsApplyResponseSchema = z.object({
 export const runtimeRouteUpdateRequestSchema = z.object({
     version_id: z.string().min(1),
     config: runtimeRouteConfigSchema.optional(),
-    // The engine stores this with the route pointer and no-ops the whole PUT — no
-    // policy store, no journal event, no edge purge — when version, digest, and
-    // hostname intent all match the stored route. Absent = always write.
+    // The engine stores this with the route pointer. When version, digest, and
+    // hostname intent all match the stored route, the engine no-ops the whole
+    // PUT: no policy store, no journal event, no edge purge. Absent = always
+    // write.
     config_digest: z.string().min(1).optional(),
     // No `changed_paths`: the runtime holds both catalogs and scopes the purge
     // from `previous_version_id` itself.
@@ -602,12 +680,12 @@ export const runtimeRouteUpdateResponseSchema = z.object({
         .min(1)
         .optional()
         .describe("Stable route_updated event id for this exact route command, including retries."),
-    ...runtimeMutationPurgeShape,
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeHostnameIntentUpdateResponseSchema = z.object({
     space_id: z.string(),
     route_count: z.number().int().nonnegative(),
-    ...runtimeMutationPurgeShape,
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeTombstonesUpdateRequestSchema = z.object({
     hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
@@ -620,34 +698,13 @@ export const runtimeTombstonesUpdateRequestSchema = z.object({
 export const runtimeTombstonesUpdateResponseSchema = z.object({
     space_id: z.string(),
     tombstone_count: z.number().int().nonnegative(),
-    ...runtimeMutationPurgeShape,
-});
-// The control plane computes prunable version ids; the engine stores the list
-// and its housekeeping tick prunes trees after re-checking live route pointers.
-// An empty list clears the policy.
-export const runtimeRetentionPolicyUpdateRequestSchema = z.object({
-    prunable_version_ids: z.array(z.string()),
-});
-export const runtimeRetentionPolicyUpdateResponseSchema = z.object({
-    space_id: z.string(),
-    prunable_count: z.number().int().nonnegative(),
-    ...runtimeMutationPurgeShape,
-});
-export const runtimeSpaceDeleteResponseSchema = z.object({
-    space_id: z.string(),
-    status: z.literal("deleted"),
-    ...runtimeMutationPurgeShape,
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeVersionDeleteResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
     status: z.literal("deleted"),
-    ...runtimeMutationPurgeShape,
-});
-export const runtimeSpaceRepairResponseSchema = z.object({
-    space_id: z.string(),
-    status: z.literal("repaired"),
-    ...runtimeMutationPurgeShape,
+    ...runtimeMutationPurgeFields,
 });
 // A pin freezes a set of blob SHAs against the collector for as long as it
 // lives. `snapshot` pins everything a set of versions plus space storage
@@ -717,7 +774,7 @@ export const runtimeZeroDbImportResponseSchema = z.object({
 });
 // Per-space generation state reported by the authed state endpoint. The
 // reconciliation sweep compares it against control-plane expectations and
-// repairs targeted mismatches — never a blanket re-sync.
+// repairs targeted mismatches, never a blanket re-sync.
 export const runtimeSpaceStateSchema = z.object({
     space_id: z.string().min(1).describe("Space whose runtime route pointers follow."),
     routes: z
@@ -791,6 +848,10 @@ export const runtimeCallbackEventSchema = z.looseObject({
         .describe("Runtime management action authorized for the operation."),
     space_id: z.string().optional().describe("Space the event applies to, when space-scoped."),
     version_id: z.string().optional().describe("Version the event applies to, when version-scoped."),
+    version_ids: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Exact versions covered by a completed space-scoped runtime operation."),
     route_name: z.string().optional().describe("Route pointer the event updated, when route-scoped."),
     hostnames: z
         .array(z.string().min(1))
@@ -862,7 +923,7 @@ export const runtimeEventsDrainRequestSchema = z
 });
 export const runtimeEventsDrainResponseSchema = z.object({
     // Cursor runtimes keep these at zero. Older engines report their legacy
-    // delivery counters here while a rolling bundle update is still converging.
+    // delivery counters here while a rolling bundle update is still syncing.
     delivered_count: z.number().int().nonnegative(),
     failed_count: z.number().int().nonnegative(),
     expired_count: z.number().int().nonnegative().optional(),
@@ -938,7 +999,7 @@ export const runtimeEngineJobRecordSchema = z.object({
 export const runtimeEngineJobCreateRequestSchema = z.object({
     type: z.string().min(1),
     payload: z.record(z.string(), z.unknown()).default({}),
-    // Unique per (type, space, operation) — create is upsert-by-key.
+    // Unique per (type, space, operation). Create is upsert-by-key.
     idempotency_key: z.string().min(1),
 });
 export const runtimeEngineJobResponseSchema = z.object({

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

@@ -1,20 +1,13 @@
 import { z } from "zod";
 /**
- * The one answer to "what is running on this space".
+ * What is running on this space.
  *
- * One published tree can carry static files, a worker and a capsule at once —
- * every space owns a site, so what answers a request is a routing decision, not
- * a kind the space declared. This is therefore two independent members rather
- * than a discriminated union: each is `null` when the live tree carries none of
- * that product, and both `null` is the overwhelmingly common answer. A static
- * space is not a degenerate app, it is the absence of one.
+ * A published tree can carry a worker and a capsule at once, so these are two
+ * independent nullable members rather than a discriminated union. Each is
+ * `null` when the live tree carries none of that product.
  *
- * When both are present the capsule wins a path conflict — it is the one that
- * owns the space's database and its transaction.
- *
- * It lives in its own module because it is the only place that needs to know
- * about both products at once. `spaces.ts` imports it to describe runtime
- * status; neither `zero.ts` nor `functions.ts` has to learn about the other.
+ * When both are present the capsule wins a path conflict: it owns the space's
+ * database and its transaction.
  */
 export declare const runtimeAppSchema: z.ZodObject<{
     capsule: z.ZodNullable<z.ZodObject<{
@@ -23,8 +16,8 @@ export declare const runtimeAppSchema: z.ZodObject<{
         serverRuntime: z.ZodLiteral<"quickjs-rust">;
         inspect: z.ZodObject<{
             policy: z.ZodEnum<{
-                public: "public";
                 private: "private";
+                public: "public";
             }>;
         }, z.core.$strict>;
         install: z.ZodObject<{
@@ -36,7 +29,7 @@ export declare const runtimeAppSchema: z.ZodObject<{
             binary: z.ZodObject<{
                 path: z.ZodLiteral<"__spacefast/zero/bin/stattic-runtime">;
                 compatibilityTarget: z.ZodObject<{
-                    profile: z.ZodLiteral<"wpcloud-linux-x86_64-gnu-v1">;
+                    profile: z.ZodLiteral<"linux-x86_64-gnu-v1">;
                     os: z.ZodLiteral<"linux">;
                     cpu: z.ZodLiteral<"x86_64">;
                     libc: z.ZodLiteral<"glibc">;
@@ -72,6 +65,8 @@ export declare const runtimeAppSchema: z.ZodObject<{
             path: z.ZodString;
         }, z.core.$strict>>>;
         sockets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        serverBundleSize: z.ZodNullable<z.ZodNumber>;
+        clientBundleSize: z.ZodNullable<z.ZodNumber>;
         migrationCount: z.ZodNumber;
         schemaHash: z.ZodNullable<z.ZodString>;
         variables: z.ZodObject<{
@@ -126,6 +121,7 @@ export declare const runtimeAppSchema: z.ZodObject<{
             gravatar: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
             spam: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
             email: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+            content: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
         }, z.core.$strip>>;
         executionState: z.ZodEnum<{
             ready: "ready";
@@ -141,14 +137,7 @@ export declare const runtimeAppSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type RuntimeApp = z.infer<typeof runtimeAppSchema>;
-/**
- * Replay of the invalidation events a live runtime emitted.
- *
- * The event shape itself is Zero's — it names mutations, changed tables and
- * changed queries, which only a capsule has — but the route that serves it is
- * the runtime family's, so the page contract lives here beside the rest of the
- * unified surface rather than inside one product.
- */
+/** Replay of the invalidation events a live runtime emitted, in Zero's event shape. */
 export declare const runtimeRealtimeEventListQuerySchema: z.ZodObject<{
     afterEventId: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -167,6 +156,7 @@ export declare const runtimeRealtimeEventListResponseSchema: z.ZodObject<{
         schemaHash: z.ZodString;
         committedAt: z.ZodString;
     }, z.core.$strict>>;
+    nextAfterEventId: z.ZodNullable<z.ZodString>;
     pagination: z.ZodObject<{
         nextCursor: z.ZodNullable<z.ZodString>;
         hasMore: z.ZodBoolean;

package/dist/contracts/runtime-app.js

@@ -3,21 +3,14 @@ import { CursorPaginationSchema } from "./common.js";
 import { functionsAppSchema } from "./functions.js";
 import { zeroAppSchema, zeroRealtimeEventSchema } from "./zero.js";
 /**
- * The one answer to "what is running on this space".
+ * What is running on this space.
  *
- * One published tree can carry static files, a worker and a capsule at once —
- * every space owns a site, so what answers a request is a routing decision, not
- * a kind the space declared. This is therefore two independent members rather
- * than a discriminated union: each is `null` when the live tree carries none of
- * that product, and both `null` is the overwhelmingly common answer. A static
- * space is not a degenerate app, it is the absence of one.
+ * A published tree can carry a worker and a capsule at once, so these are two
+ * independent nullable members rather than a discriminated union. Each is
+ * `null` when the live tree carries none of that product.
  *
- * When both are present the capsule wins a path conflict — it is the one that
- * owns the space's database and its transaction.
- *
- * It lives in its own module because it is the only place that needs to know
- * about both products at once. `spaces.ts` imports it to describe runtime
- * status; neither `zero.ts` nor `functions.ts` has to learn about the other.
+ * When both are present the capsule wins a path conflict: it owns the space's
+ * database and its transaction.
  */
 export const runtimeAppSchema = z
     .object({
@@ -29,23 +22,45 @@ export const runtimeAppSchema = z
         .describe("The live version's Functions worker, if it carries one."),
 })
     .strict();
-/**
- * Replay of the invalidation events a live runtime emitted.
- *
- * The event shape itself is Zero's — it names mutations, changed tables and
- * changed queries, which only a capsule has — but the route that serves it is
- * the runtime family's, so the page contract lives here beside the rest of the
- * unified surface rather than inside one product.
- */
+/** Replay of the invalidation events a live runtime emitted, in Zero's event shape. */
 export const runtimeRealtimeEventListQuerySchema = z
     .object({
-    afterEventId: z.string().min(1).optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(50),
+    afterEventId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Walk forward from this event id, exclusive. Omit it to start at the oldest retained event; pass the previous page's `nextAfterEventId` to continue. An id that has aged out of the retention window is rejected."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(50)
+        .describe("Maximum events to return."),
 })
     .strict();
+// Keyset, not the platform's opaque cursor: replay walks forward by event id
+// and an aged-out id is a hard error, so the response names the next
+// `afterEventId` rather than advertising a `pagination` envelope the request
+// has no `cursor` to feed. The legacy `pagination` member below is a temporary
+// back-compat exception, not the canonical shape — see its note.
 export const runtimeRealtimeEventListResponseSchema = z
     .object({
     data: z.array(zeroRealtimeEventSchema),
-    pagination: CursorPaginationSchema,
+    nextAfterEventId: z
+        .string()
+        .nullable()
+        .describe("Event id to pass as `afterEventId` for the next page; null when this page reached the newest retained event."),
+    // COMPAT (temporary back-compat, effectively durable): pre-cutover Zero
+    // capsule clients are baked per-capsule at build time and cannot be
+    // rebuilt (we don't always have capsule source). Those frozen clients page
+    // replay by reading `pagination.nextCursor` and never look at
+    // `nextAfterEventId`, so the server keeps emitting this legacy envelope
+    // alongside the flat field. `nextCursor` carries the exact same
+    // continuation value as `nextAfterEventId`, and `hasMore` mirrors it.
+    // Remove only once no frozen pre-cutover capsules remain (which may be
+    // never); until then this is the sole reason the field survives the
+    // cutover.
+    pagination: CursorPaginationSchema.describe("Legacy pagination envelope kept only for frozen pre-cutover Zero capsule clients that page by `pagination.nextCursor`. New clients read `nextAfterEventId`; `nextCursor` mirrors it exactly."),
 })
     .strict();