@spacefast/common 0.0.13 → 0.0.18

package/dist/contracts/runtime-api.js

@@ -18,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
@@ -48,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)
@@ -86,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;
@@ -136,6 +135,51 @@ export const runtimePublicExposureDescriptorSchema = z.object({
     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(),
@@ -145,13 +189,16 @@ export const runtimeAuthorizationProjectionSchema = z
     sessionVersion: z.number().int().nonnegative(),
     fence: accessFenceKindSchema,
     acquireUrl: z.string().url(),
+    accessPage: runtimeAccessPageDescriptorSchema,
     spaceClaimed: z.boolean(),
-    grants: z.array(grantSchema.extend({
+    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({
@@ -233,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."),
@@ -246,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()
@@ -257,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.
@@ -281,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
@@ -421,7 +469,6 @@ 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(),
 });
@@ -457,6 +504,11 @@ export const runtimeVersionFinalizeResponseSchema = z.object({
         .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),
     config: runtimeRouteConfigSchema.optional(),
@@ -471,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(),
@@ -647,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),
@@ -695,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)
@@ -705,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."),
@@ -716,20 +787,20 @@ 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."),
+        .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."),
+        .describe("Public-exposure digest stored by the route config write. Null means the incoming projection was unreadable."),
     previous_public_exposure: runtimePublicExposureDescriptorSchema
         .nullable()
         .optional()
@@ -784,7 +855,7 @@ export const runtimeEventsDrainResponseSchema = z.object({
         .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."),
+        .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
@@ -793,6 +864,7 @@ export const runtimeEventsDrainResponseSchema = z.object({
         .array(z.object({
         delivery_id: z.string().min(1),
         operation_id: z.string().optional(),
+        callback_token: z.string().min(1),
         event: runtimeCallbackEventSchema,
     }))
         .optional(),

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

@@ -48,13 +48,14 @@ export declare const runtimeAppSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             blockIncompatibleRollback: z.ZodLiteral<true>;
         }, z.core.$strict>;
         realtime: z.ZodObject<{
-            production: z.ZodLiteral<"stattic-central">;
+            production: z.ZodLiteral<"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>>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
     endpoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
         method: z.ZodEnum<{
             POST: "POST";
@@ -68,16 +69,17 @@ export declare const runtimeAppSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         path: z.ZodString;
     }, z.core.$strict>>>;
     sockets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    migrationCount: z.ZodNumber;
+    schemaHash: z.ZodNullable<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";
+            local: "local";
+            cast: "cast";
+            central: "central";
         }>;
         centralUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         path: z.ZodOptional<z.ZodString>;
@@ -86,6 +88,7 @@ export declare const runtimeAppSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         runPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         runUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         resourceKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ticketPath: 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>>;
@@ -124,15 +127,42 @@ export declare const runtimeAppSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         serving: "serving";
     }>;
     bundleSize: z.ZodNumber;
+    bundleSha256: z.ZodString;
     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>;
+/**
+ * Replay of the invalidation events a live runtime emitted.
+ *
+ * The event shape itself is Zero's — it names mutations, changed tables and
+ * changed queries, which only a capsule has — but the route that serves it is
+ * the runtime family's, so the page contract lives here beside the rest of the
+ * unified surface rather than inside one product.
+ */
+export declare const runtimeRealtimeEventListQuerySchema: z.ZodObject<{
+    afterEventId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export type RuntimeRealtimeEventListQuery = z.infer<typeof runtimeRealtimeEventListQuerySchema>;
+export declare const runtimeRealtimeEventListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        eventId: z.ZodString;
+        spaceId: z.ZodString;
+        versionId: z.ZodNullable<z.ZodString>;
+        runtimeKind: z.ZodLiteral<"zero">;
+        requestId: z.ZodString;
+        mutationName: z.ZodString;
+        changedTables: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        changedQueries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        schemaHash: z.ZodString;
+        committedAt: z.ZodString;
+    }, z.core.$strict>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type RuntimeRealtimeEventListResponse = z.infer<typeof runtimeRealtimeEventListResponseSchema>;

package/dist/contracts/runtime-app.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { CursorPaginationSchema } from "./common.js";
 import { functionsAppSchema } from "./functions.js";
-import { zeroAppSchema } from "./zero.js";
+import { zeroAppSchema, zeroRealtimeEventSchema } from "./zero.js";
 /**
  * The one answer to "what is running on this space".
  *
@@ -19,3 +20,23 @@ export const runtimeAppSchema = z.discriminatedUnion("runtimeKind", [
     zeroAppSchema,
     functionsAppSchema,
 ]);
+/**
+ * Replay of the invalidation events a live runtime emitted.
+ *
+ * The event shape itself is Zero's — it names mutations, changed tables and
+ * changed queries, which only a capsule has — but the route that serves it is
+ * the runtime family's, so the page contract lives here beside the rest of the
+ * unified surface rather than inside one product.
+ */
+export const runtimeRealtimeEventListQuerySchema = z
+    .object({
+    afterEventId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+})
+    .strict();
+export const runtimeRealtimeEventListResponseSchema = z
+    .object({
+    data: z.array(zeroRealtimeEventSchema),
+    pagination: CursorPaginationSchema,
+})
+    .strict();