@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/space-config.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { serviceOrigin } from "../config/domains.js";
-import { GRANT_RESOURCE_PATTERN_LIMIT, normalizeGrantResourcePattern } from "./grants.js";
+import { normalizeSlug } from "../utils/slug.js";
+import { defaultPlanNameSchema, planCatalogSchema } from "./commerce.js";
+import { GRANT_RESOURCE_PATTERN_LIMIT, identityConnectionPublicKeySchema, normalizeGrantResourcePattern, } from "./grants.js";
 export const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
 export const SPACE_CONFIG_ALIAS_FILES = [
     "spacefast.jsonc",
@@ -15,18 +17,15 @@ export const SPACE_CONFIG_ACCEPTED_FILES = [
     ...SPACE_CONFIG_ALIAS_FILES,
 ];
 /**
- * Accepted config filenames in read precedence order, highest first. Kept in
- * step with the finalizer's `CONFIG_PRECEDENCE` (crates/stattic-runtime-core
- * protocol.rs) — the runtime compile is the selection authority, and a local
- * read choosing a different file than the publish serves is a split brain.
+ * Accepted config filenames in read precedence order, highest first. Must stay
+ * in step with the finalizer's `CONFIG_ACCEPTED_FILES`
+ * (crates/stattic-runtime-core protocol.rs), which is the selection authority.
  */
 export const SPACE_CONFIG_PRECEDENCE = SPACE_CONFIG_ACCEPTED_FILES;
 export const SPACE_CONFIG_PRIVATE_FILES = [...SPACE_CONFIG_ACCEPTED_FILES];
-// Config compiler parser-safety caps (internal-docs/platform.md "Config
-// compiler scale targets"): hard from launch, enforced by ONE shared validator
-// at every intake seam — finalize for the `sf.jsonc` file, request
-// validation for the API `config` overlay. Plan policy may LOWER these caps,
-// never raise them.
+// Parser-safety caps, enforced by ONE shared validator at every intake seam:
+// finalize for the `sf.jsonc` file, request validation for the API `config`
+// overlay. Plan policy may LOWER these caps, never raise them.
 export const SPACE_CONFIG_CAPS = {
     /** Max raw `sf.jsonc` size in bytes. */
     fileBytes: 256 * 1024,
@@ -52,13 +51,52 @@ export const SPACE_CONFIG_CAPS = {
     themeNameChars: 120,
     /** Max top-level `name` (space display name) length. Matches the stored column. */
     nameChars: 255,
+    /** Max `crons` entries. One provider crontab slot each, so the cap is small and hard. */
+    crons: 8,
+    /** Max `crons[].path` length. */
+    cronPathChars: 512,
+    // `system` manifest (Partner API): the control-plane-only section a tenant's
+    // designated system space publishes. Every string is bounded and every URL is
+    // https; these caps are the enforcing authority (the Rust crate only passes
+    // the section through — it never validates it).
+    /** Max `system.presentation.name` display-name length. */
+    systemNameChars: 255,
+    /** Max length of any https URL or origin in the `system` manifest. */
+    systemUrlChars: 2048,
+    /** Max `system.hostnames.apex` length (a DNS name never exceeds 253). */
+    systemHostnameChars: 253,
+    /** Max `system.presentation.contacts` entries. */
+    systemContacts: 32,
+    /** Max length of a `system.presentation.contacts` key. */
+    systemContactKeyChars: 64,
+    /** Max length of a `system.presentation.contacts` value. */
+    systemContactValueChars: 2048,
+    /** Max `system.api.allowedOrigins` entries. */
+    systemApiAllowedOrigins: 32,
+    /** Max `system.tokenIssuers` entries. */
+    systemTokenIssuers: 16,
+    /** Max `system.tokenIssuers[].issuer` length. */
+    systemIssuerChars: 512,
+    /** Max `system.tokenIssuers[].keys` entries. */
+    systemIssuerKeys: 16,
+    /** Max `system.tokenIssuers[].keys[].kid` length. */
+    systemKeyIdChars: 64,
+    /** Exact raw Ed25519 public-key length after base64url encoding. */
+    systemPublicKeyChars: 43,
+    /** Max `system.tokenIssuers[].proof` length. */
+    systemProofChars: 4096,
+    /** Max `system.subscriptions` entries. */
+    systemSubscriptions: 32,
+    /** Max `system.subscriptions[].events` entries. */
+    systemSubscriptionEvents: 64,
+    /** Max length of a `system.subscriptions[].events` name. */
+    systemEventChars: 128,
 };
 /** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
 export const SPACE_CONFIG_SCHEMA_URL = `${serviceOrigin("www", "prod")}/schemas/sf.json`;
-// Pages theme tokens: visual values consumed by publish-rendered site pages.
-// Presentation only — never layout, behavior, or protocol.
-// Color grammar accepts hex/rgb(a)/hsl(a)/
-// named), categorically rejecting anything that could escape a style context.
+// Pages theme tokens: presentation only, never layout, behavior, or protocol.
+// The color grammar accepts hex, rgb(a), hsl(a), and named CSS colors, and
+// rejects anything that could escape a style context.
 const PAGES_COLOR_PATTERN = new RegExp([
     "^(?:",
     "#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})",
@@ -113,10 +151,7 @@ export const spacePageThemeSchema = z
     .describe("Theme tokens for Spacefast-authored pages.");
 // WordPress-compatible `theme.json` is an inference input, not configuration.
 // Only `settings.color.palette` and `settings.typography.fontFamilies` infer
-// Pages tokens; every other
-// WP theme.json key is accepted-and-ignored (this is not a full WP_Theme_JSON
-// reimplementation, just the safe subset that reaches presentation-only gate
-// pages.
+// Pages tokens; every other WP key is accepted and ignored.
 export const THEME_JSON_FILE = "theme.json";
 export const spaceBuildSettingsSchema = z
     .object({
@@ -134,9 +169,8 @@ export const spaceBuildSettingsSchema = z
     .strict()
     .describe("Remote build settings used by repository builds.");
 // Every space gets its own site, so there is nothing to place between: no mode,
-// no region knob. `burstable` is the one real provider knob left — whether the
-// space's site may burst provider PHP workers. Data location is chosen once, at
-// creation, and never changes.
+// no region knob. `burstable` says whether the space's site may burst provider
+// PHP workers. Data location is chosen once, at creation, and never changes.
 export const spacePlacementConfigSchema = z
     .object({
     burstable: z.boolean().optional(),
@@ -350,11 +384,9 @@ function refineDefaultDataSource(config, ctx) {
         });
     }
 }
-// Shared SpaceConfig fields (internal-docs/platform.md "SpaceConfig"): the
-// declarative serving config also accepted by `sf.jsonc`. Cloud-only overlay
-// fields such as pre-build data sources are added to `spaceConfigSchema` below.
-// Meta caps are the spec parser-safety numbers (title 300, description 1000,
-// image 2000); plan policy may lower them but never raise them.
+// Shared SpaceConfig fields: the declarative serving config also accepted by
+// `sf.jsonc`. Cloud-only overlay fields such as pre-build data sources are
+// added to `spaceConfigSchema` below.
 const spaceConfigBaseSchema = z.object({
     index: z
         .union([z.string().min(1), z.literal(false)])
@@ -452,13 +484,12 @@ const spaceConfigBaseSchema = z.object({
         .boolean()
         .optional()
         .describe("Accepted serving flag; runtime enforcement ships separately."),
-    // Intentionally undescribed (hidden, experimental): enables the finalize-time
-    // build pipeline (internal-docs/build-pipeline-plan.md). Accepted without
-    // diagnostics; absent/false keeps today's behavior byte-for-byte.
+    // Undescribed on purpose (hidden, experimental): enables the finalize-time
+    // build pipeline. Accepted without diagnostics.
     experimental_gutenberg: z.boolean().optional(),
-    // Intentionally minimally described (hidden, experimental): static HTML
-    // snippets, honored only when `experimental_gutenberg` is true. Byte caps are
-    // enforced by the shared validator (inject_snippet_too_large / inject_invalid).
+    // Hidden, experimental: static HTML snippets, honored only when
+    // `experimental_gutenberg` is true. Byte caps are enforced by the shared
+    // validator (inject_snippet_too_large / inject_invalid).
     inject: z
         .object({
         head: z.array(z.string()).max(SPACE_CONFIG_CAPS.injectSnippets).optional(),
@@ -493,12 +524,10 @@ export function spaceSuperpowersEnabled(config) {
     const superpowers = config?.superpowers;
     return superpowers?.enabled !== false && superpowers?.disable_all_injection !== true;
 }
-// The `sf.jsonc` FILE shape (internal-docs/platform.md "Space
-// Configuration Files"): SpaceConfig plus the editor `$schema` pointer and the
-// optional `space` link (slug or `spc_` id) resolved by CLI/publish flows.
-// Routing rules (`redirects`/`rewrites`/`headers`) are sf.jsonc keys too, but they belong
-// to the routing compiler, not to this shape: it resolves serving, they compile
-// into the canonical rules and merge behind `_redirects`/`_headers`.
+// The `sf.jsonc` FILE shape: SpaceConfig plus the editor `$schema` pointer and
+// the optional `space` link (slug or `spc_` id). Routing rules
+// (`redirects`/`rewrites`/`headers`) are sf.jsonc keys too, but they belong to
+// the routing compiler and merge behind `_redirects`/`_headers`.
 const spaceConfigPublicPatternSchema = z
     .string()
     .min(1)
@@ -560,10 +589,10 @@ export const spaceConfigFileAccessSchema = z
 /**
  * Zero: a transactional app with its own database.
  *
- * Both entries are required because Zero is never inferred. A runtime that owns
- * a database must not spring into existence from a directory shape, so the only
- * way to get one is to say so — and once said, a server or client that cannot
- * be resolved fails the publish rather than degrading to static files.
+ * Both entries are required because Zero is never inferred: a runtime that owns
+ * a database must not spring into existence from a directory shape. Once
+ * declared, a server or client that cannot be resolved fails the publish rather
+ * than degrading to static files.
  */
 export const spaceRuntimeZeroSchema = z
     .object({
@@ -584,10 +613,8 @@ export const spaceRuntimeZeroSchema = z
  * Functions: the worker `sf publish` compiles.
  *
  * Every field beyond `kind` is optional because the normal case is detection: a
- * project with `handler.ts` or an OpenNext build needs no configuration at all.
- * These exist for the layouts detection cannot guess — a worker somewhere
- * unusual, or a compatibility date the author wants pinned rather than
- * defaulted.
+ * project with `handler.ts` or an OpenNext build needs no configuration. These
+ * exist for the layouts detection cannot guess.
  */
 export const spaceRuntimeFunctionsSchema = z
     .object({
@@ -596,30 +623,313 @@ export const spaceRuntimeFunctionsSchema = z
         .string()
         .optional()
         .describe("Path to the worker entry module, relative to the published directory. " +
-        "When absent, the server detects it automatically. Naming an entry that does not exist is an error, not a silent static publish."),
+        "When absent, the server detects it automatically. Naming an entry that does not exist is an error, not a silent file-only publish."),
     database: z
         .boolean()
         .default(false)
         .describe("Give the worker `env.DB`, a D1-shaped binding to this space's database. " +
-        "This capability is declared, not detected. A capability an author did not request is authority they cannot see. Reading it from minified build output is a guess. Defaults to off, so a worker reaches nothing until it says so."),
+        "Declared, not detected: a capability an author did not request is authority they cannot see. Defaults to off."),
+    fetch: z
+        .boolean()
+        .optional()
+        .describe("Give the worker `ctx.fetch`, brokered outbound HTTP through the relay. " +
+        "Declared, not detected, like `database`. There is no schema default: a Next build gets egress unless this says false, because SSR fetches while rendering, while a hand-written worker reaches nothing until it says so."),
     compatibilityDate: z
         .string()
         .regex(/^\d{4}-\d{2}-\d{2}$/)
         .optional()
-        .describe("Runtime compatibility date this worker was written against. Pinning it makes rollback honest. Promoting an old version restores the semantics it was built with."),
+        .describe("Runtime compatibility date this worker was written against. Pinning it means promoting an old version restores the semantics it was built with."),
 })
     .describe("Functions: a worker compiled at publish time.");
 /**
- * The one runtime declaration, discriminated on `kind`.
+ * The one runtime declaration, discriminated on `kind`. A version cannot
+ * express two runtimes at once.
  *
- * One block, one kind — a version cannot express two runtimes at once, so the
- * ambiguity never has to be resolved downstream. File-only on purpose: a
- * runtime is a fact about the content of a version, so it rolls forward and
- * back with the version instead of being set through the API config overlay.
+ * File-only on purpose: a runtime is a fact about the content of a version, so
+ * it rolls forward and back with the version instead of being set through the
+ * API config overlay.
  */
 export const spaceRuntimeSchema = z
     .discriminatedUnion("kind", [spaceRuntimeZeroSchema, spaceRuntimeFunctionsSchema])
-    .describe("Runtime this version's code runs on. Omit it for a static space. Functions is also detected from the published directory when it is not stated.");
+    .describe("Runtime this version's code runs on. Omit it when the space does not run code. Functions is also detected from the published directory when it is not stated.");
+/**
+ * Scheduled requests: the provider crontab asks this space for these paths on
+ * these schedules. File-only for the same reason `runtime` is.
+ *
+ * The Rust config compiler is the selection authority for both fields; this
+ * schema exists so an editor and an agent get the same answer before publish.
+ */
+export const SPACE_CRON_NAMED_SCHEDULES = ["hourly", "daily", "twicedaily", "weekly"];
+/** Field bounds, in crontab order: minute, hour, day of month, month, weekday. */
+const CRON_FIELD_BOUNDS = [
+    [0, 59],
+    [0, 23],
+    [1, 31],
+    [1, 12],
+    [0, 7],
+];
+/** How many times per hour, day or week the `Nh`/`Nd`/`Nw` shorthand may ask. */
+const CRON_SHORTHAND_LIMITS = new Map([
+    ["h", 12],
+    ["d", 23],
+    ["w", 6],
+]);
+const CRON_STEP_MAX = 0xffff_ffff;
+function cronNumberInBounds(value, min, max) {
+    if (!/^\d+$/.test(value))
+        return false;
+    const parsed = Number(value);
+    return parsed >= min && parsed <= max;
+}
+function cronFieldIsValid(field, [min, max]) {
+    if (field.length === 0)
+        return false;
+    return field.split(",").every((item) => {
+        const slash = item.indexOf("/");
+        const range = slash === -1 ? item : item.slice(0, slash);
+        const step = slash === -1 ? undefined : item.slice(slash + 1);
+        // A step only makes sense over a span, which is what `*` and `a-b` are;
+        // `5/2` names one value and then asks to skip within it.
+        let span;
+        if (range === "*") {
+            span = true;
+        }
+        else if (range.includes("-")) {
+            const [start, end, ...rest] = range.split("-");
+            if (rest.length > 0 ||
+                start === undefined ||
+                end === undefined ||
+                !cronNumberInBounds(start, min, max) ||
+                !cronNumberInBounds(end, min, max) ||
+                Number(start) > Number(end)) {
+                return false;
+            }
+            span = true;
+        }
+        else {
+            if (!cronNumberInBounds(range, min, max))
+                return false;
+            span = false;
+        }
+        if (step === undefined)
+            return true;
+        const parsedStep = Number(step);
+        return (span &&
+            /^\d+$/.test(step) &&
+            Number.isInteger(parsedStep) &&
+            parsedStep >= 1 &&
+            parsedStep <= CRON_STEP_MAX);
+    });
+}
+/**
+ * The wp.cloud schedule grammar: a named interval, an `Nh`/`Nd`/`Nw` count, or
+ * a five-field crontab expression. No `@daily` macros and no month/day names.
+ * The provider does not accept them either.
+ */
+export function isSpaceCronSchedule(schedule) {
+    if (SPACE_CRON_NAMED_SCHEDULES.some((named) => named === schedule))
+        return true;
+    const shorthand = /^(\d+)([hdw])$/.exec(schedule);
+    const limit = CRON_SHORTHAND_LIMITS.get(shorthand?.[2] ?? "");
+    if (shorthand?.[1] !== undefined && limit !== undefined) {
+        const count = Number(shorthand[1]);
+        return count >= 1 && count <= limit;
+    }
+    const fields = schedule.split(" ");
+    return (fields.length === CRON_FIELD_BOUNDS.length &&
+        fields.every((field, index) => {
+            const bounds = CRON_FIELD_BOUNDS[index];
+            return bounds !== undefined && cronFieldIsValid(field, bounds);
+        }));
+}
+/**
+ * The artifact key for a cron path — the shared slug normalizer, so an accented
+ * path folds the same way it does everywhere else. Two paths that produce one
+ * key are rejected, so a key names exactly one schedule.
+ */
+export function spaceCronKey(path) {
+    return normalizeSlug(path);
+}
+/** Generated runtime file the serving engine reads, written only when a version declares a cron. */
+export const SPACE_CRONS_ARTIFACT_PATH = "__spacefast/crons.json";
+export const SPACE_CRONS_ARTIFACT_VERSION = 1;
+export const spaceCronSchema = z.object({
+    path: z
+        .string()
+        .max(SPACE_CONFIG_CAPS.cronPathChars)
+        .regex(/^\/[^*:?#\s\\]*$/, "must be a literal path starting with / (no * splats, :placeholders, query or fragment)")
+        .refine((path) => spaceCronKey(path).length > 0, "must contain at least one letter or digit")
+        .describe("Path this space is asked for on the schedule."),
+    schedule: z
+        .string()
+        .refine(isSpaceCronSchedule, "must be hourly, daily, twicedaily, weekly, an Nh/Nd/Nw interval, or a five-field crontab expression")
+        .describe("hourly, daily, twicedaily, weekly, an Nh/Nd/Nw interval, or a five-field crontab expression."),
+});
+export const spaceCronsSchema = z
+    .array(spaceCronSchema)
+    .max(SPACE_CONFIG_CAPS.crons)
+    .superRefine((entries, context) => {
+    // Keying on the slug catches both defects: a path written twice, and two
+    // paths that slug to one key.
+    const seenByKey = new Map();
+    entries.forEach((entry, index) => {
+        const key = spaceCronKey(entry.path);
+        const at = seenByKey.get(key);
+        if (at !== undefined) {
+            // Name the exact duplicate the author wrote: the path when it repeats
+            // verbatim, the shared key when two distinct paths collide on it.
+            const collided = entries[at];
+            context.addIssue({
+                code: "custom",
+                path: [index, "path"],
+                message: `crons entry ${at} already declares ${collided?.path === entry.path ? entry.path : key}.`,
+            });
+            return;
+        }
+        seenByKey.set(key, index);
+    });
+})
+    .describe(`Scheduled requests Spacefast issues against this space's own paths; at most ${SPACE_CONFIG_CAPS.crons} entries.`);
+/**
+ * The `system` manifest: the control-plane-only section a tenant's designated
+ * system space publishes to declare its partner-facing surface (presentation,
+ * white-label hostnames, API origins, trusted token issuers, event
+ * subscriptions).
+ *
+ * No serving behavior derives from it. The control plane freezes it at finalize
+ * and reconciles it into materialized state; other spaces' manifests are
+ * ignored. File-only, like `runtime` and `crons`: what a partner exposes is a
+ * fact about the live version, so it rolls forward and back with the version
+ * instead of living in the mutable API overlay.
+ *
+ * This zod contract is the validation authority: every string is bounded and
+ * every URL is https, with no HTML/CSS anywhere. The Rust config crate only
+ * recognizes the key and passes the section through verbatim — it never
+ * validates it and it never reaches the runtime effective-config lane.
+ */
+// `*` is excluded deliberately, not for hygiene: `system.api.allowedOrigins`
+// feeds the CORS allow-list, whose matcher treats `*` as a wildcard. A partner
+// could otherwise publish `https://*` and have the control plane reflect any
+// requesting origin back with credentials.
+const SYSTEM_HTTPS_URL_PATTERN = /^https:\/\/[^\s"'<>\\*]+$/;
+const SYSTEM_HOSTNAME_PATTERN = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)+$/;
+const systemHttpsUrlSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(SPACE_CONFIG_CAPS.systemUrlChars)
+    .regex(SYSTEM_HTTPS_URL_PATTERN, "must be an https:// URL");
+export const systemPresentationSchema = z
+    .object({
+    name: z.string().trim().min(1).max(SPACE_CONFIG_CAPS.systemNameChars).optional(),
+    logo: systemHttpsUrlSchema.optional(),
+    supportUrl: systemHttpsUrlSchema.optional(),
+    claimOrigin: systemHttpsUrlSchema.optional(),
+    accessHandoffOrigin: systemHttpsUrlSchema.optional(),
+    problemDocsBaseUrl: systemHttpsUrlSchema.optional(),
+    contacts: z
+        .record(z.string().trim().min(1).max(SPACE_CONFIG_CAPS.systemContactKeyChars), z.string().trim().min(1).max(SPACE_CONFIG_CAPS.systemContactValueChars))
+        .refine((contacts) => Object.keys(contacts).length <= SPACE_CONFIG_CAPS.systemContacts, `at most ${SPACE_CONFIG_CAPS.systemContacts} contacts`)
+        .optional()
+        .describe("Named contact URLs or addresses shown to claimants and partners."),
+})
+    .strict()
+    .describe("Partner-facing branding and links for the white-label surface.");
+export const systemHostnamesSchema = z
+    .object({
+    apex: z
+        .string()
+        .trim()
+        .min(1)
+        .max(SPACE_CONFIG_CAPS.systemHostnameChars)
+        .regex(SYSTEM_HOSTNAME_PATTERN, "must be a bare hostname (no scheme or path)")
+        .optional()
+        .describe("Apex hostname for the white-label surface."),
+})
+    .strict();
+export const systemApiSchema = z
+    .object({
+    origin: systemHttpsUrlSchema
+        .optional()
+        .describe("https origin the partner API is served from."),
+    allowedOrigins: z
+        .array(systemHttpsUrlSchema)
+        .max(SPACE_CONFIG_CAPS.systemApiAllowedOrigins)
+        .optional()
+        .describe("https origins permitted to call the partner API (CORS)."),
+})
+    .strict();
+export const systemTokenIssuerSchema = z
+    .object({
+    issuer: z
+        .string()
+        .trim()
+        .min(1)
+        .max(SPACE_CONFIG_CAPS.systemIssuerChars)
+        .describe("Issuer identifier (the iss claim tokens must carry)."),
+    keys: z
+        .array(identityConnectionPublicKeySchema)
+        .min(1)
+        .max(SPACE_CONFIG_CAPS.systemIssuerKeys)
+        .describe("Public verification keys, addressed by key id."),
+    proof: z
+        .string()
+        .trim()
+        .min(1)
+        .max(SPACE_CONFIG_CAPS.systemProofChars)
+        .optional()
+        .describe("Ownership proof that completes the two-publish issuer activation."),
+})
+    .strict();
+export const systemSubscriptionSchema = z
+    .object({
+    url: systemHttpsUrlSchema.describe("https endpoint events are delivered to."),
+    events: z
+        .array(z.string().trim().min(1).max(SPACE_CONFIG_CAPS.systemEventChars))
+        .min(1)
+        .max(SPACE_CONFIG_CAPS.systemSubscriptionEvents)
+        .describe("Event names delivered to this subscription."),
+})
+    .strict();
+export const spaceSystemManifestSchema = z
+    .object({
+    presentation: systemPresentationSchema.optional(),
+    hostnames: systemHostnamesSchema.optional(),
+    api: systemApiSchema.optional(),
+    tokenIssuers: z
+        .array(systemTokenIssuerSchema)
+        .max(SPACE_CONFIG_CAPS.systemTokenIssuers)
+        .optional()
+        .describe("Trusted token issuers registered for the tenant."),
+    subscriptions: z
+        .array(systemSubscriptionSchema)
+        .max(SPACE_CONFIG_CAPS.systemSubscriptions)
+        .optional()
+        .describe("Event subscriptions (webhooks) the tenant declares."),
+    plans: planCatalogSchema
+        .optional()
+        .describe("Per-tenant plan catalog: plan name → { features, quotas.spaces, quotaPolicy }. Feature keys validated against the live vocabulary; plan names are arbitrary."),
+    defaultPlan: defaultPlanNameSchema
+        .optional()
+        .describe("Plan unassigned principals fall back to. Must be a key in `plans`."),
+})
+    .strict()
+    .superRefine((manifest, ctx) => {
+    if (manifest.defaultPlan === undefined) {
+        return;
+    }
+    // A defaultPlan is only meaningful against a declared catalog: it must name a
+    // plan the same manifest declares, or gate resolution would fall back to a
+    // plan that does not exist.
+    if (manifest.plans === undefined || !(manifest.defaultPlan in manifest.plans)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["defaultPlan"],
+            message: "defaultPlan must be one of the plan names declared in `plans`.",
+        });
+    }
+})
+    .describe("Control-plane manifest for a tenant's designated system space. Parsed and reconciled by the control plane; ignored by other spaces.");
 export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
     $schema: z
         .string()
@@ -641,6 +951,10 @@ export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
         .describe("Display name for this space. While set, the API refuses to rename the space."),
     access: spaceConfigFileAccessSchema.optional(),
     runtime: spaceRuntimeSchema.optional(),
+    crons: spaceCronsSchema.optional(),
+    system: spaceSystemManifestSchema
+        .optional()
+        .describe("Control-plane system-space manifest. Honored only for a tenant's designated system space; other spaces' declarations are ignored."),
 });
 /**
  * The published JSON Schema artifact for `sf.jsonc`, generated from the
@@ -653,11 +967,10 @@ export function spaceConfigJsonSchema() {
         $id: SPACE_CONFIG_SCHEMA_URL,
         title: "Spacefast space configuration (sf.jsonc)",
     });
-    // `redirects`, `rewrites` and `headers` are real sf.jsonc keys, owned by the routing
-    // compiler rather than by the serving shape above — which is why they are
-    // described here instead of in the zod schema that resolves serving. An editor
-    // reading this file still has to know they exist, or the documented routing
-    // examples read as unknown keys.
+    // `redirects`, `rewrites` and `headers` are real sf.jsonc keys owned by the
+    // routing compiler, not by the serving shape above, so they are described
+    // here. Without them an editor reads the documented routing examples as
+    // unknown keys.
     return {
         ...schema,
         properties: {
@@ -666,6 +979,19 @@ export function spaceConfigJsonSchema() {
         },
     };
 }
+// The `!` and `name=:capture` of a `_redirects` line, shared by both rule
+// sections and by `config::strict::public_json_schema`.
+const SPACE_CONFIG_ROUTING_FORCE_SCHEMA = {
+    type: "boolean",
+    default: false,
+    description: "Answer even when the request path resolves to a committed file, the ! of a _redirects rule.",
+};
+const SPACE_CONFIG_ROUTING_QUERY_SCHEMA = {
+    type: "object",
+    description: 'Query parameters the request must carry, as parameter name to capture name: { "id": "id" } is the name=:capture token id=:id.',
+    propertyNames: { pattern: "^[A-Za-z][A-Za-z0-9_-]*$" },
+    additionalProperties: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9_]*$" },
+};
 const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     redirects: {
         type: "array",
@@ -688,6 +1014,8 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
                     default: 302,
                     description: "Redirect status. To serve other content under this URL, use rewrites.",
                 },
+                force: SPACE_CONFIG_ROUTING_FORCE_SCHEMA,
+                query: SPACE_CONFIG_ROUTING_QUERY_SCHEMA,
             },
             required: ["source", "destination"],
             additionalProperties: false,
@@ -713,6 +1041,13 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
                     const: "shared",
                     description: "Let shared caches store the proxy response. Absolute-URL destinations only.",
                 },
+                force: SPACE_CONFIG_ROUTING_FORCE_SCHEMA,
+                query: SPACE_CONFIG_ROUTING_QUERY_SCHEMA,
+                notFound: {
+                    type: "boolean",
+                    default: false,
+                    description: "Serve the destination with status 404, the 404 of a _redirects rule. The destination must be a path.",
+                },
             },
             required: ["source", "destination"],
             additionalProperties: false,
@@ -720,7 +1055,7 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     },
     headers: {
         type: "array",
-        description: "Response headers to set on matching requests. A _headers rule wins on the same header name.",
+        description: "Response headers to set or remove on matching requests. A _headers rule wins on the same header name.",
         items: {
             type: "object",
             properties: {
@@ -729,13 +1064,29 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
                     type: "array",
                     minItems: 1,
                     items: {
-                        type: "object",
-                        properties: {
-                            key: { type: "string", minLength: 1 },
-                            value: { type: "string" },
-                        },
-                        required: ["key", "value"],
-                        additionalProperties: false,
+                        oneOf: [
+                            {
+                                type: "object",
+                                properties: {
+                                    key: { type: "string", minLength: 1 },
+                                    value: { type: "string" },
+                                },
+                                required: ["key", "value"],
+                                additionalProperties: false,
+                            },
+                            {
+                                type: "object",
+                                properties: {
+                                    key: { type: "string", minLength: 1 },
+                                    remove: {
+                                        const: true,
+                                        description: "Remove this header instead of setting it, the !Name line of a _headers block.",
+                                    },
+                                },
+                                required: ["key", "remove"],
+                                additionalProperties: false,
+                            },
+                        ],
                     },
                 },
             },
@@ -745,16 +1096,15 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     },
 };
 /*
- * Hidden-feature discipline (internal-docs/build-pipeline-plan.md): the
- * `experimental_gutenberg` flag and its `inject` companion are ACCEPTED by the
- * parser but never published — the bare key names alone would document the
- * feature to every editor/agent reading a schema artifact. Every generator
- * that derives a public artifact from the SpaceConfig zod shape (the
- * sf.jsonc JSON Schema, the www publish-spec, the SDK OpenAPI documents)
- * must run it through this stripper. The published schemas set no
- * additionalProperties constraint, so configs that use the hidden keys still
- * validate cleanly. `inject` is removed only when it carries the SpaceConfig
- * static-placement shape so unrelated properties of the same name survive.
+ * `experimental_gutenberg` and its `inject` companion are ACCEPTED by the parser
+ * but never published: the bare key names alone would document the feature to
+ * every editor and agent reading a schema artifact. Every generator that derives
+ * a public artifact from the SpaceConfig zod shape (the sf.jsonc JSON Schema,
+ * the www publish-spec, the SDK OpenAPI documents) must run it through this
+ * stripper. The published schemas set no additionalProperties constraint, so
+ * configs using the hidden keys still validate. `inject` is removed only when it
+ * carries the SpaceConfig static-placement shape, so unrelated properties of the
+ * same name survive.
  */
 export function stripHiddenSpaceConfigKeys(schema) {
     if (Array.isArray(schema)) {
@@ -769,14 +1119,14 @@ export function stripHiddenSpaceConfigKeys(schema) {
                 if (name === "experimental_gutenberg") {
                     return false;
                 }
-                return !(name === "inject" && isHiddenInjectShape(value));
+                return !(name === "inject" && isHiddenInjectSchema(value));
             }));
             return [key, stripHiddenSpaceConfigKeys(kept)];
         }
         return [key, stripHiddenSpaceConfigKeys(entry)];
     }));
 }
-function isHiddenInjectShape(value) {
+function isHiddenInjectSchema(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return false;
     }