@spacefast/common 0.0.5 → 0.0.6

package/dist/contracts/runtime-api.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { policyDocSchema } from "./access.js";
+import { accessEventSchema, policyDocSchema } from "./access.js";
 import { conventionFilesSchema, manifestFileSchema } from "./internal.js";
 const runtimeConventionFilesSchema = conventionFilesSchema.omit({ routes: true }).strict();
 const hostCanonicalRedirectSchema = z.object({
@@ -111,15 +111,62 @@ const runtimeRouteConfigSchema = z.object({
     // 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 rules reference by
-    // `auth.password.ref` = "secret:<name>". Carries the space-password bcrypt
-    // verifier hash the runtime resolves and `password_verify`s. Explicit null
-    // clears stored secrets; absence leaves them untouched.
+    // 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(),
     // 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
+    // body) any file whose stored Content-Type matches no pattern. Patterns are
+    // exact types or `prefix/*` wildcards ("text/*"). The control plane pushes
+    // it for unclaimed anonymous spaces (no opaque binaries pre-claim); explicit
+    // null clears the stored policy — route config is rebuilt wholesale, so a
+    // claim clears it structurally on the next sync.
+    content_types: z
+        .object({
+        allowed: z.array(z.string().min(1)),
+        blocked_message: z.string().optional(),
+    })
+        .nullable()
+        .optional(),
+    // Per-space admission-control override (plan §5/§25; contract A1): the
+    // in-flight concurrency limit the engine enforces on uncacheable requests
+    // for this space, superseding SPACEFAST_UNCACHEABLE_CONC_PER_SPACE. Ops-only
+    // in V1 (set via the superadmin admission endpoint); absent means the
+    // env-knob default applies.
+    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(),
+    // Serve-time plan entitlements (proxy-routes.md: "the rule stays in your
+    // config and activates the moment you upgrade — no redeploy needed"). Stored
+    // per space beside `policy`; a `planGated` compiled proxy rule
+    // (packages/routing plan.ts) is checked against this doc at REQUEST time by
+    // runtime/redirects.php, never baked into the compiled artifact. Explicit
+    // null clears the stored doc (falls back to fail-closed); absence leaves it
+    // untouched.
+    entitlements: z
+        .object({
+        externalProxy: z.boolean(),
+    })
+        .nullable()
+        .optional(),
 });
 // Compiled SpaceConfig serving primitives (spec "Serving resolution"): the finalize
 // compiler resolves content defaults -> sf.jsonc -> space overlay into this shape;
@@ -140,6 +187,10 @@ const runtimeServingConfigSchema = z.object({
     })
         .nullable()
         .optional(),
+    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."),
     listing: z
         .boolean()
         .optional()
@@ -157,6 +208,32 @@ const runtimeServingConfigSchema = z.object({
         .nullable()
         .optional()
         .describe("Finalize-resolved listing/viewer/OG metadata (effective SpaceConfig meta); wins over session metadata."),
+    // Gate-page presentation (access-plan §5.7, X-16): finalize-compiled theme
+    // tokens (tier 1) plus the plan-gated white-label flag (tier 2). The runtime
+    // reads this shape defensively from the version's serving_config and defaults
+    // per-field; platform-LANE pages (tombstones, plan expiry, claim, invariant
+    // errors) never consume it (X-17).
+    pages: z
+        .object({
+        theme: z
+            .object({
+            accent: z.string().max(64).optional(),
+            background: z.string().max(64).optional(),
+            logo: z.string().max(2000).optional(),
+            name: z.string().max(120).optional(),
+            // Free tier ("basic color scheme + fonts"): a validated font-family
+            // stack, same grammar as pages.theme.accent/background.
+            fontFamily: z.string().max(256).optional(),
+        })
+            .optional(),
+        // Additive theme.json palette/font-family CSS custom properties
+        // (access-plan §8 tier 3 middle rung): exposes the full WP-compatible
+        // palette to custom 401.html/403.html/layout.html authors beyond the
+        // flat accent/background tokens above.
+        theme_vars: z.string().max(8192).optional(),
+        white_label: z.boolean().optional(),
+    })
+        .optional(),
     // Hidden experimental build-pipeline flag: absent on every version finalized
     // without it (byte-identical payload to today). Only ever sent as true.
     experimental_gutenberg: z.boolean().optional(),
@@ -218,8 +295,14 @@ const runtimeZeroRunSchema = z.object({
     capabilities: runtimeZeroEndpointCapabilitiesSchema.optional(),
     db: z.record(z.string(), z.unknown()).optional(),
 });
+// Gated-activation mode (plan §9, Placement V2): whether a version/import
+// installs as immediately live ("active") or staged pending an explicit
+// activation call ("activating", the engine's own fail-safe default when
+// absent). Shared by finalize and import — do not re-inline this enum.
+export const runtimeZeroModeSchema = z.enum(["active", "activating"]);
 export const runtimeVersionFinalizeRequestSchema = z.object({
     upload_id: z.string().min(1),
+    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
@@ -266,6 +349,46 @@ export const runtimeVersionFinalizeRequestSchema = z.object({
     })
         .optional()
         .describe("Channel-variant template contents, keyed by runtime route name."),
+    // Publish-baked custom gate pages (access-plan §5.7 tier 3, X-35): the
+    // finalize compiler validates the version's 401.html/403.html slot element
+    // (`<div data-sf="challenge">` / `<div data-sf="deny">`), replaces the slot's
+    // contents with the opaque v1 marker comment, and ships the baked document
+    // here. The engine stores each under the version root as
+    // `access-pages/{challenge,deny}.html` (sibling of serving.php — never a
+    // publicly served path) and unlinks stale ones on re-finalize; serving is a
+    // single str_replace of the marker with the runtime-owned functional
+    // fragment. A version finalized without a key here has no override — the
+    // default platform page renders.
+    access_pages: z
+        .object({
+        challenge: z
+            .string()
+            .max(2 * 1024 * 1024)
+            .optional()
+            .describe("Baked 401.html carrying <!--spacefast:slot:challenge:v1-->."),
+        deny: z
+            .string()
+            .max(2 * 1024 * 1024)
+            .optional()
+            .describe("Baked 403.html carrying <!--spacefast:slot:deny:v1-->."),
+    })
+        .optional(),
+    // Custom gate-page chrome (access-plan §8 tier 2): the finalize compiler
+    // validates `.spacefast/templates/layout.html`'s `<div data-sf="content">`
+    // slot, replaces its contents with the opaque v1 marker comment, and ships
+    // the baked document here. The engine stores it as
+    // `access-pages/layout.html` (sibling of the challenge/deny overrides,
+    // never a publicly served path) and unlinks it when a re-finalize omits it.
+    // Serving wraps the runtime-owned gate-page content (brand row + heading +
+    // functional fragment) in the layout's content slot with one str_replace;
+    // a missing/invalid layout falls back to the platform default chrome. Only
+    // consulted when no full custom 401.html/403.html override wins for that
+    // page (tier 1 > tier 2).
+    layout_template: z
+        .string()
+        .max(2 * 1024 * 1024)
+        .optional()
+        .describe("Baked .spacefast/templates/layout.html carrying <!--spacefast:slot:layout-content:v1-->."),
     serving: z
         .object({
         headers_exact: z.record(z.string(), z.array(z.record(z.string(), z.unknown()))).default({}),
@@ -308,6 +431,9 @@ export const runtimeVersionFinalizeResponseSchema = z.object({
     space_id: z.string(),
     version_id: z.string(),
     status: z.literal("ready"),
+    // Runtime-compiled truth from zero/endpoints-index.json. Optional so older
+    // runtimes remain parseable during rolling deploys.
+    zero_endpoint_count: z.number().int().nonnegative().optional(),
     // Open sessions: the manifest derived from what was actually uploaded
     // (path, size, streaming sha256). Absent for declared sessions.
     manifest: z.array(manifestFileSchema).optional(),
@@ -323,11 +449,22 @@ export const runtimeRouteUpdateRequestSchema = z.object({
     host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
     proxy_host_routes: runtimeRouteIntentSchema.shape.proxy_host_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,
+});
 export const runtimeRouteUpdateResponseSchema = z.object({
     space_id: z.string(),
     route_name: z.string(),
     version_id: z.string(),
 });
+export const runtimeHostnameIntentUpdateResponseSchema = z.object({
+    space_id: z.string(),
+    route_count: z.number().int().nonnegative(),
+});
 export const runtimeTombstonesUpdateRequestSchema = z.object({
     hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
     mode: z.enum(["replace", "add", "remove"]).default("replace"),
@@ -342,6 +479,31 @@ export const runtimeTombstonesUpdateResponseSchema = z.object({
     space_id: z.string(),
     tombstone_count: z.number().int().nonnegative(),
 });
+// Retention/pruning policy artifact (Placement V2 tiering, plan §8/§26): the
+// control plane computes prunable version ids; the engine stores the list and
+// its housekeeping tick prunes trees after re-checking live route pointers.
+// An empty list clears the policy.
+export const runtimeRetentionPolicyUpdateRequestSchema = z.object({
+    prunable_version_ids: z.array(z.string()),
+});
+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"),
@@ -391,14 +553,21 @@ export const runtimeSpaceExportResponseSchema = z.object({
 export const runtimeSpaceImportStartRequestSchema = z
     .object({
     version_id_map: z.record(z.string(), z.string()).optional(),
+    // Plan §9 gated activation, extended to import (I-4): shares
+    // runtimeZeroModeSchema with runtimeVersionFinalizeRequestSchema.
+    // Absent/anything other than 'active' is the engine's own fail-safe
+    // 'activating'.
+    zero_mode: runtimeZeroModeSchema.optional(),
 })
     .strict();
 // Deferred version-id mapping: control-plane-driven uploads land on the
 // runtime before the control plane has read the archive, so the freshly
-// minted target ids are supplied here before the first step.
+// minted target ids (and, for upload-sourced imports, zero_mode) are
+// supplied here before the first step.
 export const runtimeSpaceImportMapRequestSchema = z
     .object({
     version_id_map: z.record(z.string(), z.string()),
+    zero_mode: runtimeZeroModeSchema.optional(),
 })
     .strict();
 export const runtimeSpaceImportResponseSchema = z.object({
@@ -414,6 +583,42 @@ export const runtimeSpaceImportResponseSchema = z.object({
     updated_at: z.string(),
     completed_at: z.string().optional(),
 });
+const runtimeTransferBundleFileSchema = z.object({
+    path: z.string().min(1),
+    content_b64: z.string(),
+});
+export const runtimeTransferBundleSourceRequestSchema = z.object({
+    space_id: z.string().min(1),
+    version_ids: z.array(z.string().min(1)),
+    cursor: z.string().nullable(),
+});
+export const runtimeTransferBundleTargetRequestSchema = z.object({
+    space_id: z.string().min(1),
+    store: z.literal(true),
+    files: z.array(runtimeTransferBundleFileSchema),
+    done: z.boolean(),
+});
+export const runtimeTransferBundleResponseSchema = z.object({
+    chunk: z.object({ files: z.array(runtimeTransferBundleFileSchema) }),
+    next_cursor: z.string().nullable(),
+});
+export const runtimeTransferBundleStoredResponseSchema = z.object({
+    stored: z.literal(true),
+});
+export const runtimeTransferCommitRequestSchema = z.object({
+    space_id: z.string().min(1),
+    version_ids: z.array(z.string().min(1)),
+    live_version_id: z.string().nullable(),
+});
+export const runtimeTransferCommitResponseSchema = z.object({
+    installed: z.literal(true),
+});
+export const runtimeTransferAbortRequestSchema = z.object({
+    space_id: z.string().min(1),
+});
+export const runtimeTransferAbortResponseSchema = z.object({
+    aborted: z.boolean().optional(),
+});
 // Per-space generation state reported by the authed state endpoint. The
 // reconciliation sweep compares this against control-plane expectations
 // (space liveVersionId vs the runtime's route pointers) and repairs targeted
@@ -511,3 +716,67 @@ export const runtimeEventsDrainResponseSchema = z.object({
     }))
         .optional(),
 });
+// Engine job runner (plan §22, Placement V2): the box-local job runner behind
+// the two-lane tick. The control plane creates a job, drives it with repeated
+// ticks (kick-on-enqueue; the site-cron watchdog ticks the same route), and
+// reads status from either the tick response or a direct GET. Field names
+// mirror the engine's job record (§22 "Storage layout & job record").
+export const runtimeEngineJobLaneSchema = z.enum(["interactive", "bulk"]);
+export const runtimeEngineJobStatusSchema = z.enum(["pending", "running", "complete", "failed"]);
+export const runtimeEngineJobErrorSchema = z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+});
+export const runtimeEngineJobRecordSchema = z.object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    lane: runtimeEngineJobLaneSchema,
+    space_id: z.string().nullable().optional(),
+    operation_id: z.string().nullable().optional(),
+    status: runtimeEngineJobStatusSchema,
+    attempt: z.number().int().nonnegative().default(0),
+    max_attempts: z.number().int().positive().optional(),
+    progress: z
+        .object({
+        done: z.number().nonnegative().default(0),
+        total: z.number().nonnegative().default(0),
+    })
+        .optional(),
+    result: z.record(z.string(), z.unknown()).nullable().optional(),
+    error: runtimeEngineJobErrorSchema.nullable().optional(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+});
+export const runtimeEngineJobCreateRequestSchema = z.object({
+    type: z.string().min(1),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    // Unique per (type, space, operation) — create is upsert-by-key (§22).
+    idempotency_key: z.string().min(1),
+});
+export const runtimeEngineJobResponseSchema = z.object({
+    job: runtimeEngineJobRecordSchema,
+});
+// The tick response carries the ticked job's fresh state when one was
+// claimed/advanced this call, so a driver loop can usually avoid a follow-up
+// GET; `job` is absent/null when the lane had nothing eligible to run.
+export const runtimeEngineJobTickResponseSchema = z.object({
+    lane: runtimeEngineJobLaneSchema,
+    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/sites.d.ts

@@ -5,6 +5,19 @@ export declare const SiteCapacitySchema: z.ZodObject<{
     storageBytes: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type SiteCapacity = z.infer<typeof SiteCapacitySchema>;
+export declare const SitePressureSchema: z.ZodObject<{
+    ewmaLimitedPct: z.ZodOptional<z.ZodNumber>;
+    ewma429: z.ZodOptional<z.ZodNumber>;
+    ewma429PerMin: z.ZodOptional<z.ZodNumber>;
+    ewmaWorkersMax: z.ZodOptional<z.ZodNumber>;
+    ewmaCpuPct: z.ZodOptional<z.ZodNumber>;
+    lastSampleAt: z.ZodOptional<z.ZodString>;
+    consecutivePressured: z.ZodOptional<z.ZodNumber>;
+    consecutiveClean: z.ZodOptional<z.ZodNumber>;
+    pressureHoldUntil: z.ZodOptional<z.ZodString>;
+    lastBulkLaneActivityAt: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type SitePressure = z.infer<typeof SitePressureSchema>;
 export declare const SiteSchema: z.ZodObject<{
     id: z.ZodString;
     tenantId: z.ZodString;
@@ -272,8 +285,10 @@ export declare const SuperadminSiteSchema: z.ZodObject<{
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
     class: z.ZodEnum<{
-        anonymous_pool: "anonymous_pool";
+        shared: "shared";
+        dedicated: "dedicated";
         shared_org: "shared_org";
+        anonymous_pool: "anonymous_pool";
         dedicated_space: "dedicated_space";
     }>;
     providerClientId: z.ZodNullable<z.ZodString>;
@@ -359,8 +374,10 @@ export declare const SuperadminSiteListSchema: z.ZodObject<{
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
         class: z.ZodEnum<{
-            anonymous_pool: "anonymous_pool";
+            shared: "shared";
+            dedicated: "dedicated";
             shared_org: "shared_org";
+            anonymous_pool: "anonymous_pool";
             dedicated_space: "dedicated_space";
         }>;
         providerClientId: z.ZodNullable<z.ZodString>;

package/dist/contracts/sites.js

@@ -26,6 +26,27 @@ export const SiteCapacitySchema = z
         .describe("Storage budget for the site in bytes."),
 })
     .describe("Capacity accounting for shared-pool sites.");
+export const SitePressureSchema = z
+    .object({
+    ewmaLimitedPct: z.number().nonnegative().optional(),
+    ewma429: z.number().nonnegative().optional(),
+    ewma429PerMin: z.number().nonnegative().optional(),
+    ewmaWorkersMax: z.number().nonnegative().optional(),
+    ewmaCpuPct: z.number().nonnegative().optional(),
+    lastSampleAt: z.string().datetime().optional(),
+    consecutivePressured: z.number().int().nonnegative().optional(),
+    consecutiveClean: z.number().int().nonnegative().optional(),
+    // Provenance stamp for the sampler's automatic hold: set on trip to the
+    // exact hold instant it wrote, so release only clears holds the pressure
+    // pipeline itself set — never an operator-set placement hold.
+    pressureHoldUntil: z.string().datetime().optional(),
+    // Last time a bulk-lane engine job on this site reported activity via the
+    // job callbacks (runtime/callback-events.ts); the sampler discounts the
+    // CPU signal while this is within the sampling window.
+    lastBulkLaneActivityAt: z.string().datetime().optional(),
+})
+    .passthrough()
+    .describe("Placement pressure signals computed outside the request path.");
 // A Site is THE placement unit (internal-docs/platform.md "Site", `site_`):
 // one WP.Cloud site per row. Spaces are placed onto a site via `space.siteId`.
 // Provider linkage (`providerClientId`, `providerRef`) is operator-only and