@spacefast/common 0.0.11 → 0.0.13

package/dist/contracts/runtime-api.js

@@ -1,12 +1,15 @@
 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";
 const runtimeConventionFilesSchema = conventionFilesSchema.omit({ routes: true }).strict();
 const hostCanonicalRedirectSchema = z.object({
     from: z.string().min(1),
-    to: z.string().min(1),
-    status: z.literal(308).default(308),
+    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
@@ -15,18 +18,18 @@ const versionHostnameEntrySchema = z.object({
     hostname: z.string().min(1),
     version_id: z.string().min(1),
 });
-const proxyHostRouteEntrySchema = z.object({
+const staticMountRouteEntrySchema = z.object({
     hostname: z.string().min(1),
-    path_prefix: z.string().min(1).default("/"),
-    upstream: z.string().url(),
-    noindex: z.boolean().default(false),
+    path_prefix: z.string().startsWith("/").min(2),
+    target_space_id: z.string().min(1),
+    target_version_id: z.string().min(1),
 });
 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([]),
-    proxy_host_routes: z.array(proxyHostRouteEntrySchema).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
@@ -56,15 +59,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(),
@@ -78,6 +72,27 @@ export const runtimeVersionCreateResponseSchema = z.object({
     upload_id: z.string(),
     created_at: z.string(),
 });
+export const runtimeUploadSessionDescriptorSchema = z.object({
+    upload_id: z.string().min(1),
+    space_id: z.string().min(1),
+    version_id: z.string().min(1),
+    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.
+    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({}),
+});
+// 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.
+export const RUNTIME_UPLOAD_SESSION_DESCRIPTOR_MAX_BYTES = 4096;
+// 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.
@@ -85,7 +100,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(),
@@ -95,39 +109,80 @@ 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(),
+});
+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(),
+    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(),
+    })),
+})
+    .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
@@ -146,15 +201,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
@@ -251,8 +306,8 @@ const runtimeZeroEndpointCapabilitiesSchema = z
 })
     .default({});
 const runtimeZeroEndpointSchema = z.object({
-    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]),
-    path: z.string().min(1).max(2048),
+    method: zeroEndpointSchema.shape.method,
+    path: zeroEndpointSchema.shape.path,
     source: z
         .string()
         .min(1)
@@ -279,13 +334,14 @@ const runtimeZeroRunSchema = z.object({
 export const runtimeZeroModeSchema = z.enum(["active", "activating"]);
 export const runtimeVersionFinalizeRequestSchema = z.object({
     upload_id: z.string().min(1),
+    session: runtimeUploadSessionDescriptorSchema.optional(),
     zero_mode: runtimeZeroModeSchema.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(),
+    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.
+    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
@@ -356,16 +412,33 @@ 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.
+        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,
         version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
         host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
-        proxy_host_routes: runtimeRouteIntentSchema.shape.proxy_host_routes,
+        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(),
@@ -373,32 +446,53 @@ export const runtimeVersionFinalizeResponseSchema = z.object({
     // 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(),
-    // Open sessions: the manifest derived from what was actually uploaded
-    // (path, size, streaming sha256). Absent for declared sessions.
+    // 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.
     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 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
+    // hostname intent all match the stored route. Absent = always write.
+    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,
     version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
     host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
-    proxy_host_routes: runtimeRouteIntentSchema.shape.proxy_host_routes,
+    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,
-    proxy_host_routes: runtimeRouteIntentSchema.shape.proxy_host_routes,
+    static_mount_routes: runtimeRouteIntentSchema.shape.static_mount_routes,
 });
 export const runtimeRouteUpdateResponseSchema = z.object({
     space_id: z.string(),
     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.
+    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(),
@@ -429,20 +523,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"),
@@ -465,11 +545,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({
@@ -530,6 +608,7 @@ export const runtimeTransferBundleSourceRequestSchema = 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(),
 });
 export const runtimeTransferBundleTargetRequestSchema = z.object({
     space_id: z.string().min(1),
@@ -548,6 +627,7 @@ 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),
@@ -638,6 +718,56 @@ export const runtimeCallbackEventSchema = z.looseObject({
         .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."),
     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(),
@@ -649,16 +779,33 @@ 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. Non-zero 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(),
         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
@@ -707,19 +854,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),
-});

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

@@ -0,0 +1,138 @@
+import { z } from "zod";
+/**
+ * The one answer to "what is running on this space".
+ *
+ * A space is exactly one runtime kind — `versionRuntimeKind()` returns a single
+ * value and a publish carrying both declarations is refused at finalize — so
+ * this is a discriminated union rather than a bag of optional per-product
+ * fields. Anything that is not an execution tier has no member here and reads
+ * as `null`, which is the overwhelmingly common answer: a static space is not a
+ * degenerate app, it is the absence of one.
+ *
+ * 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.
+ */
+export declare const runtimeAppSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    runtimeKind: z.ZodLiteral<"zero">;
+    artifactId: z.ZodString;
+    appName: z.ZodString;
+    serverRuntime: z.ZodLiteral<"quickjs-rust">;
+    inspect: z.ZodObject<{
+        policy: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+    }, z.core.$strict>;
+    install: z.ZodObject<{
+        runtimeKind: z.ZodLiteral<"zero">;
+        engine: z.ZodLiteral<"quickjs-rust">;
+        storageRoot: z.ZodLiteral<"__spacefast/zero">;
+        artifactPath: z.ZodLiteral<"__spacefast/zero/artifact.json">;
+        configPath: z.ZodLiteral<"__spacefast/zero/config.json">;
+        binary: z.ZodObject<{
+            path: z.ZodLiteral<"__spacefast/zero/bin/stattic-runtime">;
+            compatibilityTarget: z.ZodObject<{
+                profile: z.ZodLiteral<"wpcloud-linux-x86_64-gnu-v1">;
+                os: z.ZodLiteral<"linux">;
+                cpu: z.ZodLiteral<"x86_64">;
+                libc: z.ZodLiteral<"glibc">;
+                linking: z.ZodLiteral<"dynamic">;
+                requireExecutableBit: z.ZodLiteral<true>;
+            }, z.core.$strict>;
+            sha256: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            required: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+        mysql: z.ZodObject<{
+            migrateAtFinalize: z.ZodLiteral<true>;
+            blockIncompatibleRollback: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+        realtime: z.ZodObject<{
+            production: z.ZodLiteral<"stattic-central">;
+            local: z.ZodLiteral<"foreground-cli-ws">;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    tables: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    queries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    mutations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    endpoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            POST: "POST";
+            PUT: "PUT";
+            GET: "GET";
+            HEAD: "HEAD";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            OPTIONS: "OPTIONS";
+        }>;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    sockets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    variables: z.ZodObject<{
+        source: z.ZodLiteral<"stattic-variables">;
+        names: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    realtime: z.ZodObject<{
+        mode: z.ZodEnum<{
+            "stattic-central": "stattic-central";
+            "spacefast-cast": "spacefast-cast";
+            "local-dev": "local-dev";
+            "local-websocket": "local-websocket";
+        }>;
+        centralUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        path: z.ZodOptional<z.ZodString>;
+        replayPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        replayUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        runPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        runUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        resourceKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        socketPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        spaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        versionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    runtimeKind: z.ZodLiteral<"functions">;
+    artifactId: z.ZodString;
+    appName: z.ZodString;
+    entry: z.ZodString;
+    compatibilityDate: z.ZodString;
+    compatibilityFlags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    routes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        method: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            POST: "POST";
+            PUT: "PUT";
+            GET: "GET";
+            HEAD: "HEAD";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            OPTIONS: "OPTIONS";
+        }>>>;
+        path: z.ZodString;
+        subtree: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    capabilities: z.ZodDefault<z.ZodObject<{
+        db: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        fetch: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        auth: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        env: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        realtime: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        logging: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    executionState: z.ZodEnum<{
+        ready: "ready";
+        absent: "absent";
+        serving: "serving";
+    }>;
+    bundleSize: z.ZodNumber;
+    variables: z.ZodObject<{
+        source: z.ZodLiteral<"spacefast-variables">;
+        names: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    inspect: z.ZodObject<{
+        policy: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "runtimeKind">;
+export type RuntimeApp = z.infer<typeof runtimeAppSchema>;