@spacefast/common 0.0.12 → 0.0.13

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";
@@ -57,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(),
@@ -83,7 +76,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),
@@ -108,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(),
@@ -118,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
@@ -169,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
@@ -305,12 +337,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
@@ -394,6 +425,20 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
     })
         .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 +450,12 @@ 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 runtimeRouteUpdateRequestSchema = z.object({
     version_id: z.string().min(1),
@@ -437,6 +488,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 +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"),
@@ -503,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({
@@ -529,10 +569,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.
@@ -682,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(),
@@ -693,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
@@ -751,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>;

package/dist/contracts/runtime-app.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { functionsAppSchema } from "./functions.js";
+import { zeroAppSchema } from "./zero.js";
+/**
+ * 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 const runtimeAppSchema = z.discriminatedUnion("runtimeKind", [
+    zeroAppSchema,
+    functionsAppSchema,
+]);

package/dist/contracts/sf-config-v1.d.ts

@@ -1,3 +1,4 @@
+import type { Grant } from "./grants.js";
 export declare const SF_CONFIG_V1_CANONICAL_FILE = "sf.jsonc";
 export declare const SF_CONFIG_V1_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
 /** Published JSON Schema URL for the strict `sf.jsonc` v1 contract. */
@@ -26,6 +27,9 @@ export type SfConfigV1 = {
     substitute?: {
         files: string[];
     };
+    access?: {
+        public: string[];
+    };
 };
 export type EffectiveConfigV1 = {
     version: 1;
@@ -41,6 +45,7 @@ export type EffectiveConfigV1 = {
     };
     metadata?: SfConfigV1["metadata"];
     substitute?: SfConfigV1["substitute"];
+    grants?: Grant[];
 };
 export type SfConfigV1Issue = {
     code: "config_alias" | "config_conflict" | "config_identity_moved" | "config_invalid" | "config_key_removed" | "config_unknown_key" | "serve_index_required" | "template_syntax_retired";

package/dist/contracts/sites.d.ts

@@ -407,4 +407,9 @@ export declare const SiteRebalanceResultSchema: z.ZodObject<{
         spaceId: z.ZodString;
         operationId: z.ZodString;
     }, z.core.$strip>>;
+    warning: z.ZodString;
+    domainsRequiringReverification: z.ZodArray<z.ZodObject<{
+        spaceId: z.ZodString;
+        hostname: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/contracts/sites.js

@@ -135,7 +135,7 @@ export const siteRebalanceRequestSchema = z
         .optional()
         .describe("Limit the rebalance to these space ids; omitted means every live space on the site."),
 })
-    .describe("Operator-only rebalance trigger: move spaces off this site.");
+    .describe("Operator-only rebalance trigger: move spaces off this site. This is the ONLY path that relocates an existing Space, and it is not free — see the reverification warning on the result.");
 export const SiteRebalanceResultSchema = z
     .object({
     siteId: z.string().describe("The site spaces are being moved off."),
@@ -145,5 +145,16 @@ export const SiteRebalanceResultSchema = z
         operationId: z.string().describe("The queued `space_move` operation id (`op_...`)."),
     }))
         .describe("One queued move operation per affected space."),
+    warning: z
+        .string()
+        .describe("Consequence of relocating these Spaces: each hostname is handed to another provider site, which re-runs the provider's domain-exclusivity check and is rejected unless the domain's ownership TXT record is still live in DNS."),
+    domainsRequiringReverification: z
+        .array(z.object({
+        spaceId: z.string().describe("Space the hostname serves."),
+        hostname: z
+            .string()
+            .describe("Custom hostname whose provider ownership check re-runs during the move."),
+    }))
+        .describe("Live custom hostnames on the moved Spaces. Empty means nothing customer-visible is at risk."),
 })
     .describe("Queued rebalance moves; track each operation for completion.");