@spacefast/common 0.0.23 → 0.0.26

package/dist/contracts/runtime-api.js

@@ -2,38 +2,28 @@ import { z } from "zod";
 import { accessFenceKindSchema } from "./access.js";
 import { functionsRuntimeConfigSchema } from "./functions.js";
 import { grantSchema } from "./grants.js";
-import { conventionFilesSchema, manifestFileSchema } from "./internal.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 runtimeConventionFilesSchema = conventionFilesSchema.omit({ routes: true }).strict();
 const hostCanonicalRedirectSchema = z.object({
     from: z.string().min(1),
     to: z.string().url(),
     status: z.union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)]).default(308),
 });
-// Immutable version hosts carry their own target version: the intent is the
-// COMPLETE declarative hostname map for the space (every retained ready
-// version), so a route update can never orphan an older version URL.
+// The intent is the COMPLETE declarative hostname map for the space (every
+// retained ready version), so a route update can never orphan a version URL.
 const versionHostnameEntrySchema = z.object({
     hostname: z.string().min(1),
     version_id: z.string().min(1),
 });
-// Future expansion: this intent could support explicit path-to-artifact composition
-// after independently deployable components have a real product model.
 const runtimeRouteIntentSchema = z.object({
     production_hostnames: z.array(z.string().min(1)).default([]),
     noindex_production_hostnames: z.array(z.string().min(1)).default([]),
     version_hostnames: z.array(versionHostnameEntrySchema).default([]),
     host_canonical_redirects: z.array(hostCanonicalRedirectSchema).default([]),
 });
-// Changed-path purge contract (internal-docs/platform.md "Cache Management"):
-// finalize computes the changed-path set against the previous pointer target
-// — expanded to canonical request paths (leading slash, directory-index
-// variants included) — and carries it through the runtime callback journal;
-// the callback receiver translates journal events into edge purges scoped to
-// changed paths, never a blanket purge when a diff exists. Past this cap (or
-// when no previous pointer target exists) the control plane omits the set and
-// purge handling falls back to one host-wide purge.
 export const RUNTIME_CHANGED_PATHS_MAX = 900;
 const changedPathsSchema = z
     .array(z
@@ -43,23 +33,66 @@ const changedPathsSchema = z
     .describe("Canonical request path (decoded, leading slash) whose served bytes changed."))
     .max(RUNTIME_CHANGED_PATHS_MAX)
     .optional()
-    .describe("Request paths changed from the previous pointer target. When absent, no diff is available and purge handling falls back to a host-wide purge. Echoed verbatim into the `route_updated` journal event.");
+    .describe("Request paths changed from the previous pointer target. When absent, the runtime purges the whole domain.");
 const previousVersionIdSchema = z
     .string()
     .min(1)
     .optional()
     .describe("The pointer target this activation replaces (diff baseline).");
+export const runtimePurgeReceiptSchema = z.object({
+    status: runtimePurgeStatusSchema,
+    mode: z.enum(["urls", "domain"]),
+    urls: z.number().int().nonnegative().optional(),
+});
+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,
+// 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({
+    space_id: z.string().min(1),
+    version_id: z.string().min(1),
+    view: z.enum(["source", "served"]),
+    files: z.array(z.object({
+        path: z.string().min(1),
+        size: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        content_type: z.string().min(1).optional(),
+        public: z.boolean(),
+        variant_route: z.string().min(1).optional(),
+    })),
+    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),
-    retained_files: z.array(manifestFileSchema).default([]),
+    // Retention is stated, never inferred. `all` carries every path of
+    // `reusable_version_id` forward — the runtime materializes that list from the
+    // base version's own catalog at finalize, under the space lock, which is what
+    // keeps the lazy publish path free of a pre-upload round trip. `list` retains
+    // exactly `retained_files`, and an EMPTY list is meaningful: it is a publish
+    // that drops every path the base held. `none` retains nothing.
+    //
+    // `all` and `list` both require `reusable_version_id`. Only `list` may carry
+    // `retained_files`. Inferring `all` from "base named + empty list" used to
+    // silently undo deletes — 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(),
-    // Session state stores the upload truth (spec "Upload Contract"): the version's
-    // manifest hash and the draft expiry so resume answers come from runtime state.
     manifest_hash: z.string().optional(),
     expires_at: z.string().optional(),
     metadata: z.record(z.string(), z.unknown()).default({}),
-    convention_files: runtimeConventionFilesSchema.default({}),
 });
 export const runtimeVersionCreateResponseSchema = z.object({
     space_id: z.string(),
@@ -75,26 +108,33 @@ export const runtimeUploadSessionDescriptorSchema = z.object({
     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.
+    // unbounded and unused while accepting a PUT, which is also what keeps a lazy
+    // session's descriptor inside its JWT budget. Retention itself is stated on
+    // the wire — see the create request.
+    retention: runtimeRetentionModeSchema,
     retained_files: z.array(manifestFileSchema).optional(),
     reusable_version_id: z.string().min(1).optional(),
     metadata: z.record(z.string(), z.unknown()).default({}),
-    convention_files: runtimeConventionFilesSchema.default({}),
 });
-// Candidate budget for the half that rides in the upload JWT (everything
-// except the retained manifest). This bounds signing work, but is not itself a
-// header-size proof: callback capabilities also ride in auto-finalize tokens.
+/**
+ * The retention half of a create-version body or session descriptor, spelled
+ * once. `retained_files` is omitted when empty — with an explicit `retention`
+ * that omission is unambiguous: it 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
 // to eager runtime creation rather than returning an oversized credential.
 export const RUNTIME_UPLOAD_AUTHORIZATION_HEADER_MAX_BYTES = 8 * 1024;
-// Budget for the whole descriptor, which is persisted on the version row and
-// replayed inside the durable finalize receipt.
 export const RUNTIME_UPLOAD_SESSION_STORED_MAX_BYTES = 256 * 1024;
-// Runtime-truth upload session state (spec "Upload Contract"): the resume flow asks
-// the runtime which declared files/chunks are actually present instead of guessing
-// from control-plane pending-upload state.
 export const runtimeUploadSessionResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
@@ -110,12 +150,7 @@ export const runtimeUploadSessionResponseSchema = z.object({
     })),
     // Declared paths the runtime has not committed yet.
     pending_paths: z.array(z.string()),
-    // Staged chunked-upload parts by canonical path (contiguity is checked at complete).
-    chunks: z.record(z.string(), z.array(z.number().int().positive())),
 });
-// Route-pointer config is pure serving policy plus the anonymous claim
-// countdown. Per-version serving behavior (index/fallback/listing) remains a
-// version artifact concern.
 export const visitorJwkSchema = z.object({
     kty: z.literal("OKP"),
     crv: z.literal("Ed25519"),
@@ -136,20 +171,13 @@ export const runtimePublicExposureDescriptorSchema = z.object({
     unmodeled: z.string(),
 });
 // Everything the runtime needs to render the visitor access page itself.
-// Presentation-only: which lanes exist is derived runtime-side from the
-// projected grants; this descriptor carries what the grants cannot — the
-// space's display identity, the central endpoints each lane talks to, and the
-// deterministic credential that authenticates the runtime's own
-// server-to-server exchange calls (password, verified email, request-invite)
-// so the central authority may trust the visitor context the runtime forwards.
 export const runtimeAccessPageDescriptorSchema = z
     .object({
     displayName: z.string().min(1).max(200).nullable(),
     // API-origin account lane (`/v1/access/acquire/<target>`), null until the
     // space is claimed. Doubles as the silent-SSO probe target.
     accountUrl: z.string().url().nullable(),
-    // Identity connections rendered as SSO lanes. The runtime appends
-    // `host`/`return` to `startUrl` at render time.
+    // The runtime appends `host`/`return` to `startUrl` at render time.
     connections: z.array(z.object({
         id: z.string().min(1).max(64),
         label: z.string().min(1).max(200),
@@ -158,15 +186,11 @@ export const runtimeAccessPageDescriptorSchema = z
     exchange: z
         .object({
         passwordUrl: z.string().url(),
-        // Browser entry links and integration credentials are exchanged over
-        // separate runtime-authenticated lanes. Neither credential reaches
-        // customer code.
         linkUrl: z.string().url(),
         tokenUrl: z.string().url(),
         emailUrl: z.string().url(),
         requestUrl: z.string().url(),
         logoutUrl: z.string().url(),
-        commentsConfigUrl: z.string().url().optional(),
         commentsTicketUrl: z.string().url().optional(),
         commentsVersionUrlsUrl: z.string().url().optional(),
         zeroRealtimeTicketUrl: z.string().url().optional(),
@@ -175,17 +199,11 @@ export const runtimeAccessPageDescriptorSchema = z
         .nullable(),
 })
     .strict();
-// Runtime route artifacts are compiled into an authority-keyed index. Keep a
-// hard ceiling as a last-resort safety boundary for route-apply CPU, artifact
-// size, and a compromised producer; indexing, not this limit, owns hot-path
-// performance.
 export const RUNTIME_AUTHORIZATION_GRANT_LIMIT = 1_024;
 export const runtimeAuthorizationProjectionSchema = z
     .object({
     generation: z.number().int().nonnegative(),
-    // Browser sessions follow their still-live authority references across
-    // ordinary policy/ownership projections. Only an explicit logout-all
-    // rotation invalidates every otherwise-valid session.
+    // Only an explicit logout-all rotation invalidates otherwise-valid sessions.
     sessionVersion: z.number().int().nonnegative(),
     fence: accessFenceKindSchema,
     acquireUrl: z.string().url(),
@@ -193,48 +211,78 @@ export const runtimeAuthorizationProjectionSchema = z
     spaceClaimed: z.boolean(),
     grants: z
         .array(grantSchema.extend({
-        // The durable browser session records this generation for the exact
-        // authority it acquired. Rotating or editing one credential Grant
-        // therefore removes only that authority from the session.
+        // The browser session records this per acquired authority, so rotating
+        // one Grant removes only that authority from the session.
         generation: z.number().int().positive(),
     }))
         .max(RUNTIME_AUTHORIZATION_GRANT_LIMIT),
 })
     .strict();
+// 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.
+    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(),
+    theme: z.object({
+        accent: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .nullable(),
+        hide_branding: z.boolean(),
+    }),
+    features: z.object({
+        picker: z.boolean(),
+        drawing: z.boolean(),
+        capture: z.boolean(),
+        attachments: z.boolean(),
+        notices: z.boolean(),
+    }),
+});
+const runtimeSdkProjectionSchema = z.object({
+    // Content-derived identity, used to version the injected
+    // `/__spacefast/sdk.js?v=` URL.
+    revision: z.string().min(1).max(256),
+    config: z.object({
+        cast_api_base: z.string().url().max(2000).nullable().optional(),
+        cast_ws_url: z.string().url().max(2000).nullable().optional(),
+        cast_resource_key: z.string().min(1).max(256).nullable().optional(),
+        comments: runtimeSdkCommentsSchema.nullable().optional(),
+    }),
+    // Production tag JavaScript, served inside the same loader response so
+    // private Spaces never fetch an anonymously readable per-Space artifact.
+    body: z
+        .string()
+        .max(5 * 1024 * 1024)
+        .nullable()
+        .optional(),
+});
 const runtimeRouteConfigSchema = z.object({
-    // Canonical scoped admission projection. When present it is the sole serving
-    // authority; the legacy rule document below is ignored.
+    // The sole serving admission authority when present.
     authorization: runtimeAuthorizationProjectionSchema.nullable().optional(),
-    // Digest of every input that can change anonymous/public exposure (canonical
-    // authorization boundaries, content types, proxy entitlement, and
-    // unknown serving keys). Authority-only rotation deliberately leaves it
-    // stable so Link/Person changes do not block on an unnecessary edge purge.
+    // Digest of every input that can change anonymous/public exposure.
+    // Authority-only rotation deliberately leaves it stable, so Link/Person
+    // changes do not block on an unnecessary edge purge.
     public_exposure_digest: z
         .string()
         .regex(/^[a-f0-9]{64}$/)
         .optional(),
-    // The digest detects equality; the descriptor preserves enough structure for
-    // the callback consumer to distinguish widening from narrowing without
-    // reconstructing a previous config from mutable control-plane state.
+    // The digest detects equality; the descriptor lets the consumer distinguish
+    // widening from narrowing.
     public_exposure: runtimePublicExposureDescriptorSchema.optional(),
-    // Monotonic authorization projection generation. Short-lived handoffs are
-    // bound to this exact generation, Space, and host. Browser sessions use the
-    // projection's independent sessionVersion revocation floor.
+    // Short-lived handoffs are bound to this exact generation, Space, and host.
     projection_generation: z.number().int().nonnegative().nullable().optional(),
-    // First-party visitor-token verification is explicit.
     visitor_issuer: z.string().min(1).optional(),
     visitor_jwks: visitorJwksSchema.optional(),
-    // Anonymous claim-window countdown (ISO timestamp), compiled into serving
-    // state so the runtime can render the expiry-rescue banner for visitors
-    // holding the claim-link viewer session. Null/absent once claimed.
+    // Anonymous claim-window countdown (ISO timestamp). Null/absent once claimed.
     anonymous_expires_at: z.string().nullable().optional(),
-    // Serve-time content-type allowlist. Generic serving policy: the engine has
-    // no notion of WHY a file type is blocked — it refuses (403, blocked_message
+    // Serve-time content-type allowlist: the engine refuses (403, blocked_message
     // body) any file whose stored Content-Type matches no pattern. Patterns are
-    // exact types or `prefix/*` wildcards ("text/*"). The control plane pushes
-    // it for unclaimed anonymous spaces (no opaque binaries pre-claim); explicit
-    // null clears the stored policy — route config is rebuilt wholesale, so a
-    // claim clears it structurally on the next sync.
+    // exact types or `prefix/*` wildcards ("text/*"). Explicit null clears the
+    // stored policy.
     content_types: z
         .object({
         allowed: z.array(z.string().min(1)),
@@ -242,28 +290,18 @@ const runtimeRouteConfigSchema = z.object({
     })
         .nullable()
         .optional(),
-    // Per-space admission-control override (plan §5/§25; contract A1): the
-    // in-flight concurrency limit the engine enforces on uncacheable requests
-    // for this space, superseding SPACEFAST_UNCACHEABLE_CONC_PER_SPACE. Ops-only
-    // in V1 (set via the superadmin admission endpoint); absent means the
-    // env-knob default applies.
+    // In-flight concurrency limit the engine enforces on uncacheable requests for
+    // this space, superseding SPACEFAST_UNCACHEABLE_CONC_PER_SPACE. Absent means
+    // the env-knob default applies.
     admission: z.object({ concurrency: z.number().int().positive() }).optional(),
-    // Same-host production tag JavaScript. It rides the mutable route projection
-    // so private Spaces never fetch an anonymously readable per-Space artifact.
-    tag_sdk: z
-        .object({
-        revision: z.string().min(1),
-        body: z.string().max(5 * 1024 * 1024),
-    })
-        .nullable()
-        .optional(),
-    // Serve-time plan entitlements (proxy-routes.md: "the rule stays in your
-    // config and activates the moment you upgrade — no redeploy needed"). Stored
-    // per space beside `policy`; a `planGated` compiled proxy rule
-    // (packages/routing plan.ts) is checked against this doc at REQUEST time by
-    // runtime/redirects.php, never baked into the compiled artifact. Explicit
-    // null clears the stored doc (falls back to fail-closed); absence leaves it
-    // untouched.
+    // Projection for the same-host loader at `/__spacefast/sdk.js`, and the
+    // source of the space overlay the runtime answers
+    // `/__spacefast/comments/config` from.
+    sdk: runtimeSdkProjectionSchema.nullable().optional(),
+    // Serve-time plan entitlements. A `planGated` compiled proxy rule is checked
+    // against this doc at REQUEST time, never baked into the compiled artifact.
+    // Explicit null clears the stored doc (falls back to fail-closed); absence
+    // leaves it untouched.
     entitlements: z
         .object({
         externalProxy: z.boolean(),
@@ -271,11 +309,9 @@ const runtimeRouteConfigSchema = z.object({
         .nullable()
         .optional(),
 });
-// Compiled SpaceConfig serving primitives (spec "Serving resolution"): the finalize
-// compiler resolves content defaults -> sf.jsonc -> space overlay into this shape;
-// the runtime stores it on the version's serving artifact and never re-infers. When
-// absent, the runtime infers content defaults (root index.html => website-style,
-// otherwise artifact-style listing + viewer).
+// Compiled SpaceConfig serving primitives. When absent, the runtime infers
+// content defaults (root index.html => website-style, otherwise artifact-style
+// listing + viewer).
 const runtimeServingConfigSchema = z.object({
     index: z
         .union([z.string().min(1), z.literal(false)])
@@ -304,36 +340,34 @@ const runtimeServingConfigSchema = z.object({
         .describe("Generate the single-file viewer page when a version has exactly one public file."),
     meta: z
         .object({
-        title: z.string().max(300).optional().describe("Listing, viewer, and OG title."),
-        description: z.string().max(1000).optional().describe("Listing, viewer, and OG description."),
-        image: z.string().max(2000).optional().describe("OG image path."),
+        title: z
+            .string()
+            .max(SPACE_CONFIG_CAPS.metaTitleChars)
+            .optional()
+            .describe("Listing, viewer, and OG title."),
+        description: z
+            .string()
+            .max(SPACE_CONFIG_CAPS.metaDescriptionChars)
+            .optional()
+            .describe("Listing, viewer, and OG description."),
+        image: z.string().max(SPACE_CONFIG_CAPS.metaImageChars).optional().describe("OG image path."),
+        favicon: z
+            .string()
+            .max(SPACE_CONFIG_CAPS.metaImageChars)
+            .optional()
+            .describe("Favicon path."),
     })
         .nullable()
         .optional()
-        .describe("Finalize-resolved listing, viewer, and OG metadata (effective SpaceConfig metadata). This value wins over session metadata."),
+        .describe("Finalize-resolved listing, viewer, sharing, and browser icon metadata (effective SpaceConfig metadata). This value wins over session metadata."),
     pages: runtimePagesSchema.optional(),
-    // Hidden experimental build-pipeline flag: absent on every version finalized
-    // without it (byte-identical payload to today). Only ever sent as true.
+    // Hidden experimental build-pipeline flag. Only ever sent as true.
     experimental_gutenberg: z.boolean().optional(),
-    // Platform-owned head metadata injection for normal HTML finalization. This is
-    // distinct from the hidden user build-pipeline flag: it only enables missing
-    // title/description/OG/Twitter tags derived from finalized SpaceConfig meta.
+    // Platform-owned head metadata injection: enables missing title,
+    // description, favicon, OG, and Twitter tags from finalized SpaceConfig meta.
     platform_meta: z.boolean().optional(),
-    // Platform-owned same-host SDK bootstrap metadata. The public Cast base is
-    // finalized with the version so locally-created remote runtimes do not guess
-    // between local/prod; resource identity is also per-version because one
-    // runtime/Atomic can serve many spaces.
-    spacefast_sdk: z
-        .object({
-        cast_api_base: z.string().url().max(2000).nullable().optional(),
-        cast_ws_url: z.string().url().max(2000).nullable().optional(),
-        cast_resource_key: z.string().min(1).max(256).nullable().optional(),
-        published_comments: z.boolean().optional(),
-    })
-        .optional(),
-    // CP-validated inject snippets (<= 8 KB each, <= 16 per array); sent only
-    // when experimental_gutenberg is true. Char caps here are a sanity bound —
-    // the byte caps are enforced by the shared SpaceConfig validator.
+    // Sent only when experimental_gutenberg is true. The char caps here are a
+    // sanity bound; the byte caps live in the shared SpaceConfig validator.
     inject: z
         .object({
         head: z.array(z.string().max(8192)).max(16).optional(),
@@ -375,61 +409,49 @@ const runtimeZeroRunSchema = z.object({
     capabilities: runtimeZeroEndpointCapabilitiesSchema.optional(),
     db: z.record(z.string(), z.unknown()).optional(),
 });
-// Gated-activation mode (plan §9, Placement V2): whether a version/import
-// installs as immediately live ("active") or staged pending an explicit
-// activation call ("activating", the engine's own fail-safe default when
-// absent). Shared by finalize and import — do not re-inline this enum.
-export const runtimeZeroModeSchema = z.enum(["active", "activating"]);
+// One variable scope as finalize resolved it. Secrets are NEVER resolved: a
+// secret match at any scope fails the publish in the control plane, so the
+// runtime receives the flag and no value.
+const runtimeVariableScopeSchema = z.object({
+    kind: z.enum(["space", "principal"]),
+    values: z.record(z.string().min(1), z.object({
+        value: z.string().optional(),
+        secret: z.boolean(),
+        channelValues: z.record(z.string().min(1), z.string()).optional(),
+    })),
+});
+const runtimeSubstitutionChannelSchema = z.object({
+    name: z.string().min(1).max(128),
+    route_name: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[A-Za-z0-9._-]+$/)
+        .describe("Runtime route name this channel's variant files serve under."),
+});
 export const runtimeVersionFinalizeRequestSchema = z.object({
     upload_id: z.string().min(1),
     session: runtimeUploadSessionDescriptorSchema.optional(),
-    zero_mode: runtimeZeroModeSchema.optional(),
     zero: zeroRuntimeConfigSchema.optional(),
     // Dispatch configuration for a Functions version. Absent for static versions,
-    // and absent when a worker was published while no execution host is
-    // configured — the version then serves as pure static content, because a
-    // config is the only thing that makes the origin dispatch at all.
+    // 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.
     functions: functionsRuntimeConfigSchema.optional(),
-    convention_files: runtimeConventionFilesSchema.optional(),
-    // Finalize-time `{{ vars.NAME }}` substitution output (spec "Variable
-    // rules"): substituted bytes replace the served files; the engine keeps the
-    // pre-substitution bytes in `files-original/` so declared-sha dedup still
-    // verifies upload identity. Keyed by canonical version-relative path.
-    template_files: z
-        .record(z.string().min(1).describe("Canonical committed path declared in `templates`."), z
-        .string()
-        .max(2 * 1024 * 1024)
-        .describe("Substituted file contents (secret values never reach this payload)."))
-        .refine((files) => Object.keys(files).length <= 100, {
-        message: "template_files supports up to 100 entries.",
-    })
-        .optional()
-        .describe("Substituted template contents applied over the committed tree at finalize."),
-    // Per-channel template variants (spec "Per-channel values"): channelValues
-    // overrides compile channel-specific contents of declared template files as
-    // channel-scoped serving artifacts. Keyed by RUNTIME ROUTE NAME (route names
-    // are runtime-only vocabulary; the live channel serves via `production`).
-    // Variants serve only on the route's hosts — permanent Version URLs always
-    // serve the version's own finalize-resolved values.
-    template_variants: z
-        .record(z
-        .string()
-        .min(1)
-        .max(128)
-        .regex(/^[A-Za-z0-9._-]+$/)
-        .describe("Runtime route name this variant set serves."), z
-        .record(z.string().min(1).describe("Canonical committed path declared in `templates`."), z
-        .string()
-        .max(2 * 1024 * 1024)
-        .describe("Variant file contents (secret values never reach this payload)."))
-        .refine((files) => Object.keys(files).length <= 100, {
-        message: "template_variants supports up to 100 entries per route.",
-    }))
-        .refine((routes) => Object.keys(routes).length <= 8, {
-        message: "template_variants supports up to 8 routes.",
-    })
-        .optional()
-        .describe("Channel-variant template contents, keyed by runtime route name."),
+    // 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.
+    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
+    // under the route name that serves them.
+    channels: z.array(runtimeSubstitutionChannelSchema).max(8).optional(),
+    // Hostnames this space answers on, which convention compilation needs to tell
+    // an internal redirect from an external proxy. Only the control plane knows
+    // the assignment.
+    routing_assigned_hostnames: z.array(z.string().min(1)).optional(),
     // Finalize-rendered Pages documents stored outside the public file tree.
     page_artifacts: z
         .record(z.string().min(1).max(240), z.string().max(2 * 1024 * 1024))
@@ -437,18 +459,24 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
         message: "page_artifacts supports up to 100,000 rendered documents.",
     })
         .optional(),
+    // Serving inputs only the control plane can produce. The compiled routing
+    // rules are NOT here: the finalizer compiles `_redirects`, `_headers` and the
+    // config's routing sections from the staged files itself.
     serving: z
         .object({
-        headers_exact: z.record(z.string(), z.array(z.record(z.string(), z.unknown()))).default({}),
-        headers_pattern: z.array(z.record(z.string(), z.unknown())).default([]),
-        redirects_exact: z.record(z.string(), z.array(z.record(z.string(), z.unknown()))).default({}),
-        redirects_pattern: z.array(z.record(z.string(), z.unknown())).default([]),
+        noindexHost: z.boolean().optional(),
         config: runtimeServingConfigSchema.optional(),
-        // Trusted Zero endpoint source compiled by the runtime into private
-        // endpoint-specific JS, QuickJS bytecode, and PHP manifest invoke actions.
+        // 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.
+        platform_csp_sources: z
+            .record(z.string().min(1).max(64), z.array(z.string().min(1).max(512)).max(16))
+            .optional(),
         zero_endpoints: z.array(runtimeZeroEndpointSchema).max(128).optional(),
-        // Trusted Zero run-handler source compiled into private artifacts for
-        // non-HTTP Zero execution surfaces. These are not PHP route actions.
+        // Non-HTTP Zero execution surfaces; not PHP route actions.
         zero_runs: z.array(runtimeZeroRunSchema).max(128).optional(),
     })
         .optional(),
@@ -460,10 +488,8 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
             .default("production")
             .describe("Runtime route-pointer to activate; route names are runtime-only vocabulary."),
         config: runtimeRouteConfigSchema.optional(),
-        // Same contract as the route PUT's config_digest: stored with the
-        // pointer so later conditional route PUTs can no-op against it.
+        // Same contract as the route PUT's config_digest.
         config_digest: z.string().min(1).optional(),
-        changed_paths: changedPathsSchema,
         previous_version_id: previousVersionIdSchema,
         production_hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
         noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
@@ -486,23 +512,107 @@ export const runtimeReadinessTargetSchema = z.object({
     path: z.string().startsWith("/"),
     expected_statuses: z.array(z.union([runtimePublicReadinessStatusSchema, z.literal(404)])).min(1),
 });
+// The scalars the control plane stores instead of a file list. Both digests are
+// over the version's own catalog: `source` folds path → uploaded sha (two
+// publishes of identical bytes agree even when serving config differs),
+// `served` folds what the version actually answers with, per channel included.
+export const runtimeCatalogDigestsSchema = z.object({
+    source: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    served: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+});
+// What this publish changed against the version it supersedes. The runtime
+// diffs two catalogs it already holds; the control plane persists the three
+// counts for the changelog and forwards nothing.
+export const runtimeCatalogDeltaSchema = z.object({
+    added: z.number().int().nonnegative(),
+    changed: z.number().int().nonnegative(),
+    removed: z.number().int().nonnegative(),
+});
+// 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.
+export const runtimeCompileDiagnosticSchema = z.object({
+    severity: z.enum(["info", "warning", "error"]),
+    code: z.string().min(1),
+    message: z.string(),
+    path: z.string().optional(),
+    details: z.record(z.string(), z.unknown()).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
+// verdict.
+export const runtimeCompiledRoutingSchema = z.object({
+    redirect_rule_count: z.number().int().nonnegative(),
+    header_rule_count: z.number().int().nonnegative(),
+    proxy_rule_count: z.number().int().nonnegative(),
+    proxy_rules: z
+        .array(z.object({ source: z.string(), destination: z.string() }))
+        .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: PHP passes the object through rather than restating it.
+// Everything else here is read back from the version's immutable metadata;
+// timings cannot be, because they differ on every run. `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"),
-    // Runtime-compiled truth from zero/endpoints-index.json. Optional so older
-    // runtimes remain parseable during rolling deploys.
     zero_endpoint_count: z.number().int().nonnegative().optional(),
-    // Canonical runtime-committed manifest (path, size, streaming sha256).
-    // Returned by both first and idempotent finalize responses so recovery
-    // never needs an already-consumed upload session.
+    // 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.
+    diagnostics: z.array(runtimeCompileDiagnosticSchema).default([]),
+    routing: runtimeCompiledRoutingSchema.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?".
+    variable_digests: z.record(z.string().min(1), z.string()).default({}),
+    system_variable_dependencies: z.array(z.string().min(1)).default([]),
+    // Canonical runtime-committed manifest, returned by both first and idempotent
+    // finalize responses so recovery never needs a consumed upload session.
     manifest: z.array(manifestFileSchema).optional(),
+    catalog_digests: runtimeCatalogDigestsSchema.optional(),
+    // Absent when this version supersedes nothing, or when the previous version
+    // predates the catalog.
+    delta: runtimeCatalogDeltaSchema.optional(),
+    // The served public image the space card shows for this version, chosen from
+    // 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."),
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeZeroMigrationsApplyResponseSchema = z.object({
     space_id: z.string(),
@@ -512,12 +622,12 @@ export const runtimeZeroMigrationsApplyResponseSchema = z.object({
 export const runtimeRouteUpdateRequestSchema = z.object({
     version_id: z.string().min(1),
     config: runtimeRouteConfigSchema.optional(),
-    // Canonical digest of `config` (control-plane routeConfigDigest). The engine
-    // stores it with the route pointer and no-ops the whole PUT — no policy
-    // store, no journal event, no edge purge — when version, digest, and
+    // 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.
     config_digest: z.string().min(1).optional(),
-    changed_paths: changedPathsSchema,
+    // No `changed_paths`: the runtime holds both catalogs and scopes the purge
+    // from `previous_version_id` itself.
     previous_version_id: previousVersionIdSchema,
     production_hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
     noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
@@ -535,36 +645,36 @@ export const runtimeRouteUpdateResponseSchema = z.object({
     route_name: z.string(),
     version_id: z.string(),
     // True when the engine skipped the write because version_id, config_digest,
-    // and hostname intent all matched the stored route: nothing was journaled,
-    // so callers skip the event drain too.
+    // and hostname intent all matched: nothing was journaled, so callers skip the
+    // event drain too.
     unchanged: z.boolean().optional(),
     activation_event_id: z
         .string()
         .min(1)
         .optional()
         .describe("Stable route_updated event id for this exact route command, including retries."),
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeHostnameIntentUpdateResponseSchema = z.object({
     space_id: z.string(),
     route_count: z.number().int().nonnegative(),
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeTombstonesUpdateRequestSchema = z.object({
     hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
     mode: z.enum(["replace", "add", "remove"]).default("replace"),
-    // Optional reason/category drive a differentiated tombstone variant on the
-    // runtime (e.g. csam -> bare 404, copyright -> 451, suspension -> 402). The
-    // runtime falls back to a generic 404 when both are absent, so these are
-    // additive and back-compatible.
+    // Select a differentiated tombstone variant (csam -> bare 404, copyright ->
+    // 451, suspension -> 402); absent means a generic 404.
     reason: z.string().optional(),
     category: z.string().optional(),
 });
 export const runtimeTombstonesUpdateResponseSchema = z.object({
     space_id: z.string(),
     tombstone_count: z.number().int().nonnegative(),
+    ...runtimeMutationPurgeFields,
 });
-// Retention/pruning policy artifact (Placement V2 tiering, plan §8/§26): the
-// control plane computes prunable version ids; the engine stores the list and
-// its housekeeping tick prunes trees after re-checking live route pointers.
+// 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()),
@@ -572,127 +682,83 @@ export const runtimeRetentionPolicyUpdateRequestSchema = z.object({
 export const runtimeRetentionPolicyUpdateResponseSchema = z.object({
     space_id: z.string(),
     prunable_count: z.number().int().nonnegative(),
-});
-export const runtimeSpaceDeleteResponseSchema = z.object({
-    space_id: z.string(),
-    status: z.literal("deleted"),
+    ...runtimeMutationPurgeFields,
 });
 export const runtimeVersionDeleteResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
     status: z.literal("deleted"),
-});
-export const runtimeSpaceRepairResponseSchema = z.object({
-    space_id: z.string(),
-    status: z.literal("repaired"),
-});
-const runtimeExportImportStatusSchema = z.enum([
-    "waiting_for_archive",
-    "pending",
-    "running",
-    "complete",
+    ...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
+// currently reference; `shas` pins an explicit list. `expires_at` is the
+// engine's hard backstop, so a mover that dies mid-flight never wedges the
+// collector.
+const runtimeSha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+export const runtimePinCreateRequestSchema = z.union([
+    z.object({
+        mode: z.literal("snapshot"),
+        version_ids: z.array(z.string().min(1)),
+        include_uploads: z.boolean().default(true),
+        ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .max(24 * 60 * 60),
+    }),
+    z.object({
+        mode: z.literal("shas"),
+        shas: z.array(runtimeSha256Schema).max(100_000),
+        ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .max(24 * 60 * 60),
+    }),
 ]);
-export const runtimeSpaceExportStartRequestSchema = z
-    .object({
-    version_ids: z.array(z.string().min(1)).min(1).optional(),
-    // include_files=false produces a metadata-only archive that cannot be
-    // imported as a serving Space. Recorded in stattic.json `includes`.
-    include_files: z.boolean().optional(),
-})
-    .strict();
-export const runtimeSpaceExportResponseSchema = z.object({
-    type: z.literal("space_export"),
-    export_id: z.string(),
-    space_id: z.string(),
-    status: runtimeExportImportStatusSchema,
-    cursor: z.number().int().nonnegative(),
-    processed_files: z.number().int().nonnegative(),
-    total_files: z.number().int().nonnegative(),
-    version_ids: z.array(z.string()),
-    archive_size: z.number().int().nonnegative().optional(),
-    // SHA-256 of the finished archive (64 lowercase hex), computed once at
-    // completion so the control plane can expose SpaceExport.archive.sha256.
-    archive_sha256: z.string().optional(),
-    created_at: z.string(),
-    updated_at: z.string(),
-    completed_at: z.string().optional(),
-});
-export const runtimeSpaceImportStartRequestSchema = z
-    .object({
-    version_id_map: z.record(z.string(), z.string()).optional(),
-    // Plan §9 gated activation, extended to import (I-4): shares
-    // runtimeZeroModeSchema with runtimeVersionFinalizeRequestSchema.
-    // Absent/anything other than 'active' is the engine's own fail-safe
-    // 'activating'.
-    zero_mode: runtimeZeroModeSchema.optional(),
-})
-    .strict();
-// Deferred version-id mapping: control-plane-driven uploads land on the
-// runtime before the control plane has read the archive, so the freshly
-// minted target ids (and, for upload-sourced imports, zero_mode) are
-// supplied here before the first step.
-export const runtimeSpaceImportMapRequestSchema = z
-    .object({
-    version_id_map: z.record(z.string(), z.string()),
-    zero_mode: runtimeZeroModeSchema.optional(),
-})
-    .strict();
-export const runtimeSpaceImportResponseSchema = z.object({
-    type: z.literal("space_import"),
-    import_id: z.string(),
-    space_id: z.string(),
-    status: runtimeExportImportStatusSchema,
-    cursor: z.number().int().nonnegative(),
-    processed_files: z.number().int().nonnegative(),
-    total_files: z.number().int().nonnegative(),
-    version_ids: z.array(z.string()),
-    created_at: z.string(),
-    updated_at: z.string(),
-    completed_at: z.string().optional(),
-});
-const runtimeTransferBundleFileSchema = z.object({
-    path: z.string().min(1),
-    content_b64: z.string(),
-});
-export const runtimeTransferBundleSourceRequestSchema = z.object({
+export const runtimePinCreateResponseSchema = z.object({
     space_id: z.string().min(1),
-    version_ids: z.array(z.string().min(1)),
-    cursor: z.string().nullable(),
-    include_serving_state: z.boolean().optional(),
+    pin_id: z.string().min(1),
+    expires_at: z.string().min(1),
+    sha_count: z.number().int().nonnegative(),
 });
-export const runtimeTransferBundleTargetRequestSchema = z.object({
+export const runtimePinReleaseResponseSchema = z.object({
     space_id: z.string().min(1),
-    store: z.literal(true),
-    files: z.array(runtimeTransferBundleFileSchema),
+    pin_id: z.string().min(1),
+    released: z.boolean(),
+});
+// Path-blind on purpose: the response names only the SHAs the space does not
+// already hold.
+export const runtimeBlobsHaveRequestSchema = z.object({
+    shas: z.array(runtimeSha256Schema),
+});
+export const runtimeBlobsHaveResponseSchema = z.object({
+    missing: z.array(runtimeSha256Schema),
+});
+export const runtimeBlobPutResponseSchema = z.object({
+    sha256: runtimeSha256Schema,
+    size: z.number().int().nonnegative(),
+    stored: z.boolean(),
+});
+// The mirror of the paged export lane: pages replay in the same table/ordering
+// against a schema the target already migrated. Import is idempotent on primary
+// key, so a retried page is not a duplicate row.
+export const runtimeZeroDbImportRequestSchema = z.object({
+    schema_hash: z.string().min(1),
+    table: z.string().min(1),
+    rows: z.array(z.record(z.string(), z.unknown())).max(1_000),
     done: z.boolean(),
 });
-export const runtimeTransferBundleResponseSchema = z.object({
-    chunk: z.object({ files: z.array(runtimeTransferBundleFileSchema) }),
-    next_cursor: z.string().nullable(),
-});
-export const runtimeTransferBundleStoredResponseSchema = z.object({
-    stored: z.literal(true),
-});
-export const runtimeTransferCommitRequestSchema = z.object({
-    space_id: z.string().min(1),
-    version_ids: z.array(z.string().min(1)),
-    live_version_id: z.string().nullable(),
-    install_serving_state: z.boolean().optional(),
-});
-export const runtimeTransferCommitResponseSchema = z.object({
-    installed: z.literal(true),
-});
-export const runtimeTransferAbortRequestSchema = z.object({
+export const runtimeZeroDbImportResponseSchema = z.object({
     space_id: z.string().min(1),
-});
-export const runtimeTransferAbortResponseSchema = z.object({
-    aborted: z.boolean().optional(),
+    version_id: z.string().min(1),
+    table: z.string().min(1),
+    imported: z.number().int().nonnegative(),
 });
 // Per-space generation state reported by the authed state endpoint. The
-// reconciliation sweep compares this against control-plane expectations
-// (space liveVersionId vs the runtime's route pointers) and repairs targeted
-// mismatches — never a blanket re-sync (internal-docs/platform.md "Cache
-// Management": missed callbacks degrade to bounded staleness).
+// reconciliation sweep compares it against control-plane expectations and
+// 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
@@ -703,12 +769,6 @@ export const runtimeSpaceStateSchema = z.object({
         .int()
         .nonnegative()
         .describe("Hostnames the runtime serves a tombstone page for on this space."),
-    // Optional for the same reason the whole block is: the control plane deploys
-    // in one step while engines pull their bundle on their own schedule, so every
-    // field added here is absent on the fleet for hours. Absence means "this
-    // engine cannot report hostname scope", never "the scope is empty" — callers
-    // must degrade rather than sign a narrower callback claim than the engine
-    // will report.
     intent_hostnames: z
         .array(z.string().min(1))
         .optional()
@@ -739,25 +799,19 @@ export const runtimeStateResponseSchema = z.object({
         .min(1)
         .optional()
         .describe("Runtime engine bundle revision. Missing means the engine predates revision state."),
-    // Optional generation-state fields (absent on engines predating the reconcile
-    // handshake; the sweep treats absence as "cannot compare").
     routes_generation: z
         .string()
         .nullable()
         .optional()
-        .describe("Active route-index generation id (routes/current.php pointer)."),
+        .describe("Active route-index generation id (routes/current.json pointer)."),
     spaces: z
         .array(runtimeSpaceStateSchema)
         .optional()
         .describe("Per-space route-pointer state for reconcile comparison."),
 });
-// Runtime callback journal event (internal-docs/platform.md "Cache
-// Management"): the engine journals every management mutation and delivers it
-// at-least-once to the control-plane callback receiver, which translates
-// serving-affecting events into provider edge purges. `event_id` is the stable
-// journal id — purge enqueues are idempotent on (event_id, hostname) so
-// replays are no-ops. The object is intentionally loose: engines may journal
-// extra diagnostic fields without breaking older control planes.
+// Runtime callback journal event. Purging is complete (or durably queued for a
+// maintenance retry) before a mutation returns, so this lane carries only
+// observability and background events.
 export const runtimeCallbackEventSchema = z.looseObject({
     event: z
         .string()
@@ -767,7 +821,7 @@ export const runtimeCallbackEventSchema = z.looseObject({
         .string()
         .min(1)
         .optional()
-        .describe("Stable journal/callback id; purge handling replays as no-ops on this id."),
+        .describe("Stable journal/callback id for idempotent delivery."),
     operation_id: z
         .string()
         .optional()
@@ -815,6 +869,13 @@ const runtimeEventDeliveryIdentitySchema = z.object({
     delivery_id: z.string().min(1),
 });
 const runtimeEventDrainSessionIdSchema = z.string().min(1).max(128);
+export const runtimeJournalCursorSchema = z
+    .object({
+    file: z.string(),
+    offset: z.number().int().nonnegative(),
+    inode: z.number().int().nonnegative().optional(),
+})
+    .strict();
 export const runtimeEventsDrainRequestSchema = z
     .object({
     session_id: runtimeEventDrainSessionIdSchema,
@@ -841,49 +902,55 @@ export const runtimeEventsDrainRequestSchema = z
         context.addIssue({ code: "custom", message: "A drain page requires page_id." });
 });
 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.
     delivered_count: z.number().int().nonnegative(),
     failed_count: z.number().int().nonnegative(),
-    expired_count: z
-        .number()
-        .int()
-        .nonnegative()
-        .optional()
-        .describe("Undeliverable callbacks dropped after exceeding the attempt cap."),
+    expired_count: z.number().int().nonnegative().optional(),
     returned_count: z.number().int().nonnegative().optional(),
     pending_count: z
         .number()
         .int()
         .nonnegative()
         .optional()
-        .describe("Journal entries not returned because of the response cap, another active lease, or this session's failed-delivery deferral. A non-zero value means a later page or repair session still has work."),
-    // The drain is pull-first: the caller IS the control plane and is blocked on
-    // this response, so the engine hands its journal back here instead of posting
-    // each event over a separate HTTP round trip. Processing replays are no-ops
-    // on (event_id, hostname).
+        .describe("Whether the journal has records beyond this page. A non-zero value means a later drain still has work."),
     events: z
         .array(z.object({
         delivery_id: z.string().min(1),
         operation_id: z.string().optional(),
-        callback_token: z.string().min(1),
         event: runtimeCallbackEventSchema,
     }))
         .optional(),
+    cursor: runtimeJournalCursorSchema
+        .optional()
+        .describe("The journal commit coordinate. Absent on pre-cursor runtime bundles."),
 });
-export const runtimeEventsAckRequestSchema = z.object({
-    session_id: runtimeEventDrainSessionIdSchema,
-    deliveries: z.array(runtimeEventDeliveryIdentitySchema).max(100),
+export const runtimeEventsAckRequestSchema = z
+    .object({
+    // The cursor is the authoritative commit coordinate.
+    cursor: runtimeJournalCursorSchema.optional(),
+    session_id: runtimeEventDrainSessionIdSchema.optional(),
+    deliveries: z.array(runtimeEventDeliveryIdentitySchema).max(100).default([]),
+})
+    .superRefine((value, context) => {
+    if (!value.cursor && (!value.session_id || value.deliveries.length === 0)) {
+        context.addIssue({
+            code: "custom",
+            message: "An event acknowledgement requires a cursor or legacy deliveries.",
+        });
+    }
 });
 export const runtimeEventsAckResponseSchema = z.object({
     acknowledged_count: z.number().int().nonnegative(),
     idempotent_count: z.number().int().nonnegative(),
     stale_count: z.number().int().nonnegative(),
+    cursor: runtimeJournalCursorSchema
+        .optional()
+        .describe("The committed journal coordinate. Absent after a legacy delivery acknowledgement."),
 });
-// Engine job runner (plan §22, Placement V2): the box-local job runner behind
-// the two-lane tick. The control plane creates a job, drives it with repeated
-// ticks (kick-on-enqueue; the site-cron watchdog ticks the same route), and
-// reads status from either the tick response or a direct GET. Field names
-// mirror the engine's job record (§22 "Storage layout & job record").
-export const runtimeEngineJobLaneSchema = z.enum(["interactive", "bulk"]);
+// One lane; the enum keeps its single value because the engine's job record and
+// tick response still carry the field.
+export const runtimeEngineJobLaneSchema = z.literal("bulk");
 export const runtimeEngineJobStatusSchema = z.enum(["pending", "running", "complete", "failed"]);
 export const runtimeEngineJobErrorSchema = z.object({
     code: z.string().min(1),
@@ -912,15 +979,13 @@ 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 (§22).
+    // Unique per (type, space, operation) — create is upsert-by-key.
     idempotency_key: z.string().min(1),
 });
 export const runtimeEngineJobResponseSchema = z.object({
     job: runtimeEngineJobRecordSchema,
 });
-// The tick response carries the ticked job's fresh state when one was
-// claimed/advanced this call, so a driver loop can usually avoid a follow-up
-// GET; `job` is absent/null when the lane had nothing eligible to run.
+// `job` is absent/null when the lane had nothing eligible to run.
 export const runtimeEngineJobTickResponseSchema = z.object({
     lane: runtimeEngineJobLaneSchema,
     job: runtimeEngineJobRecordSchema.nullable().optional(),