@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/runtime-api.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import { accessEventSchema, policyDocSchema } from "./access.js";
+import { accessFenceKindSchema } from "./access.js";
+import { functionsRuntimeConfigSchema } from "./functions.js";
+import { grantSchema } from "./grants.js";
 import { conventionFilesSchema, manifestFileSchema } from "./internal.js";
 import { runtimePagesSchema } from "./pages.js";
 import { zeroEndpointSchema, zeroRuntimeConfigSchema } from "./zero.js";
@@ -16,18 +18,13 @@ const versionHostnameEntrySchema = z.object({
     hostname: z.string().min(1),
     version_id: z.string().min(1),
 });
-const staticMountRouteEntrySchema = z.object({
-    hostname: z.string().min(1),
-    path_prefix: z.string().startsWith("/").min(2),
-    target_space_id: z.string().min(1),
-    target_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([]),
-    static_mount_routes: z.array(staticMountRouteEntrySchema).optional(),
 });
 // Changed-path purge contract (internal-docs/platform.md "Cache Management"):
 // finalize computes the changed-path set against the previous pointer target
@@ -46,7 +43,7 @@ const changedPathsSchema = z
     .describe("Canonical request path (decoded, leading slash) whose served bytes changed."))
     .max(RUNTIME_CHANGED_PATHS_MAX)
     .optional()
-    .describe("Request paths changed vs the previous pointer target; absent = no diff available (host-wide purge fallback). Echoed verbatim into the route_updated journal event.");
+    .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.");
 const previousVersionIdSchema = z
     .string()
     .min(1)
@@ -57,15 +54,6 @@ export const runtimeVersionCreateRequestSchema = z.object({
     files: z.array(manifestFileSchema),
     retained_files: z.array(manifestFileSchema).default([]),
     reusable_version_id: z.string().min(1).optional(),
-    // "declared" sessions validate every PUT against the declared manifest.
-    // "open" sessions (internal-docs/platform.md "Upload Contract" shape 2) have
-    // no manifest: the runtime enforces path policy and the session caps per
-    // PUT, computes streaming hashes, and finalize derives the manifest.
-    // Plan-policy caps ride in session state, never in the upload JWT, and are
-    // valid only on open sessions.
-    session_mode: z.enum(["declared", "open"]).default("declared"),
-    max_total_bytes: z.number().int().positive().optional(),
-    max_file_count: z.number().int().positive().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(),
@@ -83,7 +71,6 @@ export const runtimeUploadSessionDescriptorSchema = z.object({
     upload_id: z.string().min(1),
     space_id: z.string().min(1),
     version_id: z.string().min(1),
-    session_mode: z.literal("declared"),
     expires_at: z.string(),
     manifest_hash: z.string().optional(),
     files: z.array(manifestFileSchema),
@@ -94,10 +81,14 @@ export const runtimeUploadSessionDescriptorSchema = z.object({
     metadata: z.record(z.string(), z.unknown()).default({}),
     convention_files: runtimeConventionFilesSchema.default({}),
 });
-// Budget for the half that rides in the upload JWT (everything except the
-// retained manifest): 4 KiB of JSON keeps the signed token inside common 8 KiB
-// header buffers, since it is sent on every PUT.
+// 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.
 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;
@@ -108,7 +99,6 @@ export const runtimeUploadSessionResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
     upload_id: z.string(),
-    session_mode: z.enum(["declared", "open"]),
     created_at: z.string().nullable(),
     expires_at: z.string().nullable(),
     manifest_hash: z.string().nullable(),
@@ -118,39 +108,128 @@ export const runtimeUploadSessionResponseSchema = z.object({
         sha256: z.string().optional(),
         uploaded: z.boolean(),
     })),
-    // Declared paths the runtime has not committed yet (empty for open sessions).
+    // 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: THE resolved access policy plus
-// the anonymous claim countdown. Space passwords are NOT a separate config
-// channel — they ride inside `policy.rules` as a password challenge rule (one
-// access model, spec "Runtime"). Per-version serving behavior
-// (index/fallback/listing) is a version artifact concern, never route config.
+// 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"),
+    kid: z.string().min(1),
+    alg: z.literal("EdDSA"),
+    x: z.string().min(1),
+    use: z.literal("sig").optional(),
+});
+export const visitorJwksSchema = z.object({
+    keys: z.array(visitorJwkSchema).min(1),
+});
+export const runtimePublicExposureDescriptorSchema = z.object({
+    v: z.number().int().positive(),
+    public: z.boolean(),
+    authorizationDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    contentTypes: z.array(z.string()).nullable(),
+    externalProxy: z.boolean(),
+    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.
+    connections: z.array(z.object({
+        id: z.string().min(1).max(64),
+        label: z.string().min(1).max(200),
+        startUrl: z.string().url(),
+    })),
+    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(),
+        credential: z.string().min(32).max(256),
+    })
+        .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.
+    sessionVersion: z.number().int().nonnegative(),
+    fence: accessFenceKindSchema,
+    acquireUrl: z.string().url(),
+    accessPage: runtimeAccessPageDescriptorSchema,
+    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.
+        generation: z.number().int().positive(),
+    }))
+        .max(RUNTIME_AUTHORIZATION_GRANT_LIMIT),
+})
+    .strict();
 const runtimeRouteConfigSchema = z.object({
-    // THE unified policy lane ({ rules: RuntimeRule[] }) the runtime enforcer
-    // (access-rules.php) evaluates first-match-wins for every host entry this
-    // space serves — route hosts, custom domains, and immutable version hosts
-    // alike. Carries platform + file + cloud rules (platform prepended, always
-    // wins). Explicit null clears the stored policy; absence leaves it untouched.
-    policy: policyDocSchema.nullable().optional(),
-    // Serving-secret map (name -> value) the policy's password acquires
-    // reference by `ref` = "secret:<name>". Carries the space-password bcrypt
-    // verifier hash (and the compiled `_headers` basicAuth credential hashes)
-    // the runtime resolves and `password_verify`s. Explicit null clears stored
-    // secrets; absence leaves them untouched.
-    secrets: z.record(z.string().min(1), z.string().min(1)).nullable().optional(),
-    // Space session version (access-plan §3.1): the runtime rejects a visitor
-    // token whose `sv` claim mismatches this, and derives the space-local `pw:`
-    // key from the password secret + this value. Absent = 0.
-    session_version: z.number().int().nonnegative().nullable().optional(),
+    // Canonical scoped admission projection. When present it is the sole serving
+    // authority; the legacy rule document below is ignored.
+    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.
+    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.
+    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.
+    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_expires_at: z.string().nullable().optional(),
     // Serve-time content-type allowlist. Generic serving policy: the engine has
-    // no notion of WHY a space is restricted — it refuses (403, blocked_message
+    // no notion of WHY a file type is blocked — it 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
@@ -169,15 +248,15 @@ const runtimeRouteConfigSchema = z.object({
     // in V1 (set via the superadmin admission endpoint); absent means the
     // env-knob default applies.
     admission: z.object({ concurrency: z.number().int().positive() }).optional(),
-    // Durable revocation SET (access-plan revocation hardening): every
-    // currently-revoked link:/invite:/svc: grant id, computed from the
-    // control-plane's Postgres projection (access/resolve.ts
-    // `revocationsForSpace`). The runtime REPLACES its revocations store's
-    // grant bucket with exactly this set on every sync — the backstop that
-    // converges even when the instant best-effort revoke_grant/unrevoke_grant
-    // call was dropped. `subs` (JWT-subject revocations) are left untouched.
-    // Absence leaves the stored set untouched.
-    revocations: z.array(z.string().min(1)).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
@@ -201,7 +280,7 @@ const runtimeServingConfigSchema = z.object({
     index: z
         .union([z.string().min(1), z.literal(false)])
         .optional()
-        .describe("Directory index file name, or false to disable directory index resolution."),
+        .describe("Directory index file name, or `false` to disable directory index resolution."),
     fallback: z
         .object({
         path: z.string().min(1).describe("Committed file served when no exact route matches."),
@@ -214,7 +293,7 @@ const runtimeServingConfigSchema = z.object({
     clean_urls: z
         .boolean()
         .optional()
-        .describe("Serve flat `<name>.html` files at their extensionless URLs (W7.1). Absent = default: on unless the fallback is the 200-status SPA shape."),
+        .describe("Serves flat `<name>.html` files at their extensionless URLs (W7.1). Defaults to on, unless the fallback is the 200-status SPA shape."),
     listing: z
         .boolean()
         .optional()
@@ -225,13 +304,13 @@ 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/OG title."),
-        description: z.string().max(1000).optional().describe("Listing/viewer/OG description."),
+        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."),
     })
         .nullable()
         .optional()
-        .describe("Finalize-resolved listing/viewer/OG metadata (effective SpaceConfig meta); wins over session metadata."),
+        .describe("Finalize-resolved listing, viewer, and OG 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.
@@ -249,6 +328,7 @@ const runtimeServingConfigSchema = 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
@@ -305,12 +385,11 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
     session: runtimeUploadSessionDescriptorSchema.optional(),
     zero_mode: runtimeZeroModeSchema.optional(),
     zero: zeroRuntimeConfigSchema.optional(),
-    // The version's authoritative ready timestamp (epoch seconds), passed by the
-    // control plane when the version already reached ready (re-finalize, import
-    // re-materialization, provider migration). The engine stamps it ONCE into the
-    // version metadata; access-window rules (windowDays) compare against this
-    // stored value — never a filesystem mtime that resets on rebuilds.
-    ready_at: z.number().int().positive().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.
+    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
@@ -390,10 +469,23 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
         noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
         version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
         host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
-        static_mount_routes: runtimeRouteIntentSchema.shape.static_mount_routes,
     })
         .optional(),
 });
+const runtimePublicReadinessStatusSchema = z.union([
+    z.literal(200),
+    z.literal(301),
+    z.literal(302),
+    z.literal(303),
+    z.literal(307),
+    z.literal(308),
+    z.literal(401),
+    z.literal(403),
+]);
+export const runtimeReadinessTargetSchema = z.object({
+    path: z.string().startsWith("/"),
+    expected_statuses: z.array(z.union([runtimePublicReadinessStatusSchema, z.literal(404)])).min(1),
+});
 export const runtimeVersionFinalizeResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
@@ -405,6 +497,17 @@ export const runtimeVersionFinalizeResponseSchema = z.object({
     // Returned by both first and idempotent finalize responses so recovery
     // never needs an already-consumed upload session.
     manifest: z.array(manifestFileSchema).optional(),
+    readiness_target: runtimeReadinessTargetSchema,
+    activation_event_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Stable route_updated event id when finalize also activated a route."),
+});
+export const runtimeZeroMigrationsApplyResponseSchema = z.object({
+    space_id: z.string(),
+    version_id: z.string(),
+    applied: z.literal(true),
 });
 export const runtimeRouteUpdateRequestSchema = z.object({
     version_id: z.string().min(1),
@@ -420,14 +523,12 @@ export const runtimeRouteUpdateRequestSchema = z.object({
     noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
     version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
     host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
-    static_mount_routes: runtimeRouteIntentSchema.shape.static_mount_routes,
 });
 export const runtimeHostnameIntentUpdateRequestSchema = z.object({
     production_hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
     noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
     version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
     host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
-    static_mount_routes: runtimeRouteIntentSchema.shape.static_mount_routes,
 });
 export const runtimeRouteUpdateResponseSchema = z.object({
     space_id: z.string(),
@@ -437,6 +538,11 @@ export const runtimeRouteUpdateResponseSchema = z.object({
     // and hostname intent all matched the stored route: 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."),
 });
 export const runtimeHostnameIntentUpdateResponseSchema = z.object({
     space_id: z.string(),
@@ -467,20 +573,6 @@ export const runtimeRetentionPolicyUpdateResponseSchema = z.object({
     space_id: z.string(),
     prunable_count: z.number().int().nonnegative(),
 });
-// Instant per-grant tombstone (access-plan revocation hardening): the
-// control plane's best-effort synchronous call at revoke/unrevoke time,
-// hitting the SAME `revocations.json` the durable `config.revocations` full
-// replace (above) also converges. `grant` must be a `link:`/`invite:`/`svc:`
-// row id — the runtime rejects anything else.
-export const runtimeGrantRevocationRequestSchema = z.object({
-    grant: z.string().min(1),
-});
-export const runtimeGrantRevocationResponseSchema = z.object({
-    space_id: z.string(),
-    target_type: z.literal("grant"),
-    grant: z.string(),
-    revoked: z.boolean(),
-});
 export const runtimeSpaceDeleteResponseSchema = z.object({
     space_id: z.string(),
     status: z.literal("deleted"),
@@ -503,11 +595,9 @@ const runtimeExportImportStatusSchema = z.enum([
 export const runtimeSpaceExportStartRequestSchema = z
     .object({
     version_ids: z.array(z.string().min(1)).min(1).optional(),
-    // Honest export options (spec SpaceExportRequest): include_files=false
-    // produces a config-only archive; include_explicit_config=false skips the
-    // space access policy entry. Recorded in stattic.json `includes`.
+    // 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(),
-    include_explicit_config: z.boolean().optional(),
 })
     .strict();
 export const runtimeSpaceExportResponseSchema = z.object({
@@ -529,10 +619,6 @@ export const runtimeSpaceExportResponseSchema = z.object({
 });
 export const runtimeSpaceImportStartRequestSchema = z
     .object({
-    // Version installation and target-policy replacement are separate trust
-    // decisions. Managed imports always pass false; trusted full-restore tools
-    // must opt in explicitly before archive upload.
-    install_access_policy: z.boolean().optional(),
     version_id_map: z.record(z.string(), z.string()).optional(),
     // Plan §9 gated activation, extended to import (I-4): shares
     // runtimeZeroModeSchema with runtimeVersionFinalizeRequestSchema.
@@ -611,12 +697,26 @@ export const runtimeSpaceStateSchema = z.object({
     space_id: z.string().min(1).describe("Space whose runtime route pointers follow."),
     routes: z
         .record(z.string(), z.string())
-        .describe("Route pointer map: route name -> version id currently compiled for serving."),
+        .describe("Route pointer map from route name to version id currently compiled for serving."),
     tombstone_count: z
         .number()
         .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()
+        .describe("Exact hostname set in the space's current route intent."),
+    hostnames: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Exact hostname union that a space deletion event carries from route intent and tombstones."),
 });
 export const runtimeHealthResponseSchema = z.object({
     ok: z.literal(true),
@@ -659,7 +759,10 @@ export const runtimeStateResponseSchema = z.object({
 // replays are no-ops. The object is intentionally loose: engines may journal
 // extra diagnostic fields without breaking older control planes.
 export const runtimeCallbackEventSchema = z.looseObject({
-    event: z.string().min(1).describe("Journal event name (e.g. route_updated, space_deleted)."),
+    event: z
+        .string()
+        .min(1)
+        .describe("Journal event name, for example `route_updated` or `space_deleted`."),
     event_id: z
         .string()
         .min(1)
@@ -669,6 +772,10 @@ export const runtimeCallbackEventSchema = z.looseObject({
         .string()
         .optional()
         .describe("Control-plane operation the management call ran under."),
+    operation_action: z
+        .string()
+        .optional()
+        .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."),
     route_name: z.string().optional().describe("Route pointer the event updated, when route-scoped."),
@@ -680,8 +787,58 @@ export const runtimeCallbackEventSchema = z.looseObject({
     changed_paths_known: z
         .boolean()
         .optional()
-        .describe("True when changed_paths is the complete diff, including a known-empty diff. Absent on older engines, where an empty array remains the host-wide fallback."),
+        .describe("True when `changed_paths` is the complete diff, including a known-empty diff. On older engines this field is absent. There, an empty array remains the host-wide fallback."),
     previous_version_id: previousVersionIdSchema,
+    previous_public_exposure_digest: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("Public-exposure digest stored before a route config write. Field presence proves the route already existed. Null means the previous projection was unreadable."),
+    public_exposure_digest: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("Public-exposure digest stored by the route config write. Null means the incoming projection was unreadable."),
+    previous_public_exposure: runtimePublicExposureDescriptorSchema
+        .nullable()
+        .optional()
+        .describe("Public-exposure descriptor stored before a route config write. Null means the previous projection was unreadable."),
+    public_exposure: runtimePublicExposureDescriptorSchema
+        .nullable()
+        .optional()
+        .describe("Public-exposure descriptor stored by the route config write. Null means the incoming projection was unreadable."),
+});
+const runtimeEventDeliveryIdentitySchema = z.object({
+    event_id: z.string().min(1),
+    delivery_id: z.string().min(1),
+});
+const runtimeEventDrainSessionIdSchema = z.string().min(1).max(128);
+export const runtimeEventsDrainRequestSchema = z
+    .object({
+    session_id: runtimeEventDrainSessionIdSchema,
+    page_id: runtimeEventDrainSessionIdSchema.optional(),
+    target_event_id: z.string().min(1).max(128).optional(),
+    exclude_deliveries: z
+        .array(runtimeEventDeliveryIdentitySchema)
+        .max(100)
+        .optional()
+        .describe("Failed deliveries from the immediately preceding page."),
+    finish_session: z.boolean().optional(),
+})
+    .superRefine((value, context) => {
+    if (value.finish_session === true) {
+        if (value.page_id || value.target_event_id || value.exclude_deliveries) {
+            context.addIssue({
+                code: "custom",
+                message: "A finished drain session cannot request a page.",
+            });
+        }
+        return;
+    }
+    if (!value.page_id)
+        context.addIssue({ code: "custom", message: "A drain page requires page_id." });
 });
 export const runtimeEventsDrainResponseSchema = z.object({
     delivered_count: z.number().int().nonnegative(),
@@ -693,16 +850,34 @@ export const runtimeEventsDrainResponseSchema = z.object({
         .optional()
         .describe("Undeliverable callbacks dropped after exceeding the attempt cap."),
     returned_count: z.number().int().nonnegative().optional(),
-    // Pull fallback: events whose push origin was unreachable are handed back to
-    // the drain caller (the control plane) instead of rotting in the journal.
-    // Processing replays are no-ops on (event_id, hostname).
+    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).
     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(),
 });
+export const runtimeEventsAckRequestSchema = z.object({
+    session_id: runtimeEventDrainSessionIdSchema,
+    deliveries: z.array(runtimeEventDeliveryIdentitySchema).max(100),
+});
+export const runtimeEventsAckResponseSchema = z.object({
+    acknowledged_count: z.number().int().nonnegative(),
+    idempotent_count: z.number().int().nonnegative(),
+    stale_count: z.number().int().nonnegative(),
+});
 // 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
@@ -751,19 +926,3 @@ export const runtimeEngineJobTickResponseSchema = z.object({
     job: runtimeEngineJobRecordSchema.nullable().optional(),
     drained: z.boolean().optional(),
 });
-// The management pull action for the Views panel (access-plan §5.6b, X-37):
-// `GET /access-events?file&offset&limit` — a cursor-resumed read of the
-// runtime's own per-hostname NDJSON access-event journal. `cursor` is the
-// position after the last returned event (feed it back verbatim); `done` is
-// false only when the response was truncated by `limit`; `dropped` totals the
-// writer's `.dropped` sidecars (events skipped past the per-file byte cap).
-export const runtimeAccessEventsCursorSchema = z.object({
-    file: z.string().min(1).nullable(),
-    offset: z.number().int().nonnegative(),
-});
-export const runtimeAccessEventsResponseSchema = z.object({
-    events: z.array(accessEventSchema).default([]),
-    cursor: runtimeAccessEventsCursorSchema,
-    done: z.boolean(),
-    dropped: z.number().int().nonnegative().default(0),
-});