@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/functions.js

@@ -3,46 +3,33 @@ import { appRoutePathSchema, executionBase64Schema, executionCapabilitiesSchema,
 /**
  * Spacefast Functions: tenant workers run as Cloudflare Dynamic Workers.
  *
- * The shape of this product follows from two constraints that are not
- * negotiable and that together rule out the obvious architecture:
+ * Two constraints shape the product:
  *
- * 1. **Cloudflare is reached from wp.cloud, never from the control plane.**
- *    The control plane records intent; the space's own origin performs every
+ * 1. Cloudflare is reached from wp.cloud, never from the control plane. The
+ *    control plane records intent; the space's own origin makes every
  *    Cloudflare call.
- * 2. **Every asset is served by wp.cloud.** We deliberately decline
- *    Cloudflare's static-asset support for user workers. A worker receives
- *    only the requests that could not be answered from bytes on disk, and
- *    `/_next/static/*` and friends never leave our origin.
+ * 2. Every asset is served by wp.cloud. A worker receives only the requests
+ *    that could not be answered from bytes on disk, so `/_next/static/*` and
+ *    friends never leave our origin.
  *
- * Dynamic Workers is what makes both hold at once. There is no upload: a
- * version's bundle stays in its own content store on wp.cloud, and the host
- * worker pulls it on demand through the Worker Loader binding. So there is no
- * script lifecycle here — no namespace, no script name, no tag budget, no
- * eviction, no garbage collection — because there is no artefact of ours living
- * on Cloudflare to manage. What Cloudflare holds is a warm isolate, which is a
- * cache, not a record.
- *
- * That also keeps the exit cheap. The contract below is "here is a module
- * graph, here is its configuration, run it", which is workerd's own shape; the
- * managed runtime is an implementation of it rather than the thing we built
- * against.
- *
- * What the worker gets in exchange is the thing we could not build: a real V8
- * isolate that runs npm packages and framework output — OpenNext Next.js among
- * them — without us having to sandbox any of it.
+ * Dynamic Workers holds both at once. There is no upload: a version's bundle
+ * stays in its own content store on wp.cloud and the host worker pulls it
+ * through the Worker Loader binding, so no artefact of ours lives on Cloudflare
+ * and there is no script lifecycle to manage. What the worker buys is a real V8
+ * isolate running npm packages and framework output, OpenNext Next.js among
+ * them, without us sandboxing any of it.
  *
  * The cost is that the worker is a continent away from the space's MySQL.
  * `ctx.db` therefore travels back over an HTTPS relay to the same PHP broker
  * the local tier speaks to over a pipe, which is slower and batched rather
  * than transactional. That is why capsules are a different product rather
- * than a placement option — see `endpointIsPortable` in `./execution.js`.
+ * than a placement option. See `endpointIsPortable` in `./execution.js`.
  */
 /**
- * The tag a compiled worker artifact carries — in `functionsSourceFinalizeSchema`
- * and the runtime config built from it — so the PHP origin can tell what it is
- * dispatching (`functions-dispatch.php` refuses a config tagged anything else).
- * It is a property of the artifact the tree produced, not a kind a space or a
- * version declares: a publish can carry this beside a capsule.
+ * The tag a compiled worker artifact carries, so the PHP origin can tell what
+ * it is dispatching. `functions-dispatch.php` refuses any other tag. It is a
+ * property of the artifact, not a kind a space or a version declares: a publish
+ * can carry this beside a capsule.
  */
 export const FUNCTIONS_RUNTIME_KIND = "functions";
 export const FUNCTIONS_SOURCE_METADATA_KEY = "spacefastFunctions";
@@ -52,7 +39,7 @@ export const FUNCTIONS_RUNTIME_ROUTE_PATHS = {
     /** Where a dispatched worker calls back for brokered capabilities. */
     relay: `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/relay`,
     /**
-     * Where the execution host asks the space origin to drop cached responses —
+     * Where the execution host asks the space origin to drop cached responses:
      * an OpenNext `revalidatePath` must reach the CDN in front of wp.cloud, and
      * only the origin can speak for its own cache. Authenticated with the
      * version-scoped purge credential in the `sf-purge-token` request header.
@@ -61,89 +48,161 @@ export const FUNCTIONS_RUNTIME_ROUTE_PATHS = {
 };
 /**
  * The header the execution host presents at the origin purge route. Outside the
- * `sf-fx-` namespace on purpose: that prefix names dispatch instructions the
- * origin SENDS, and is stripped from anything inbound before tenant code — a
- * purge call is the host speaking for itself, like a relay call.
+ * `sf-fx-` namespace because that prefix names dispatch instructions the origin
+ * SENDS, and is stripped from anything inbound before tenant code.
  */
 export const FUNCTIONS_PURGE_TOKEN_HEADER = "sf-purge-token";
+/**
+ * The credential a space origin presents to the execution host on every
+ * dispatch (`sf-fx-dispatch-token`), and the audience that identifies it.
+ *
+ * It is a PER-SITE token, not a fleet secret. The control plane mints one
+ * Ed25519 JWT per wp.cloud box, bound to that box's `runtime_instance_id`, and
+ * writes it into that box's persistent data. The host verifies the signature
+ * against the control plane's public key and takes the site identity from the
+ * verified claim rather than from anything the caller asserts.
+ *
+ * Tenant PHP runs on the same box and can read the box's own configuration, so
+ * assume the tenant can read this credential. A per-site token read once still
+ * speaks only for its own site: the host refuses any bundle whose signed token
+ * names a different `runtime_instance_id`. Signing is EdDSA rather than HMAC so
+ * that no signing material sits on the edge, where a host compromise would mint
+ * dispatch credentials for the whole fleet.
+ */
+export const FUNCTIONS_DISPATCH_TOKEN_AUD = "spacefast-functions-dispatch";
+/**
+ * Pinned by every verifier rather than read from the token's own header.
+ * Accepting the presented `alg` is how `alg: none` forgeries work.
+ */
+export const FUNCTIONS_TOKEN_ALG = "EdDSA";
+/**
+ * Ten years, like the bundle and relay credentials: the token is not re-mintable
+ * on any request path. It reaches a box only through a wp.cloud persistent-data
+ * sync at provisioning and on maintenance sweeps, so a shorter clock would take
+ * a quiet box offline rather than protect it. Scope is the boundary, and
+ * rotating the platform signing key invalidates every token at once.
+ */
+export const FUNCTIONS_DISPATCH_TOKEN_TTL_SECONDS = 10 * 365 * 24 * 60 * 60;
+/**
+ * What the execution host requires of a dispatch credential before it believes
+ * anything else in the request. One signing key mints every platform token, so
+ * the pinned audience is what keeps them from meaning one authority.
+ */
+export const functionsDispatchTokenClaimsSchema = z.object({
+    aud: z.literal(FUNCTIONS_DISPATCH_TOKEN_AUD),
+    runtime_instance_id: z.string().min(1),
+    exp: z.number(),
+    nbf: z.number().optional(),
+});
+/**
+ * The claims carried by the token inside a signed bundle or seed URL. The
+ * audience stays open because both artifacts share this shape and are separated
+ * by their own audience check at the point of use: a bundle grant must never
+ * authorise a seed read.
+ */
+export const functionsArtifactTokenClaimsSchema = z.object({
+    aud: z.string().min(1),
+    runtime_instance_id: z.string().min(1),
+    space_id: z.string().min(1),
+    version_id: z.string().min(1),
+    sha256: z.string().min(1),
+    exp: z.number(),
+    nbf: z.number().optional(),
+});
+const functionsTokenHeaderSchema = z.object({ alg: z.literal(FUNCTIONS_TOKEN_ALG) });
+/**
+ * Undecodable text and a failed schema return the same null on purpose: a reader
+ * that told them apart would tell a forger which half was wrong.
+ */
+function parsedTokenJson(json, schema) {
+    try {
+        const parsed = schema.safeParse(JSON.parse(json));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a compact JWT's protected header declares the one algorithm this
+ * platform signs with. Pinned rather than trusted: a verifier that takes the
+ * token's own word for `alg` accepts `alg: none`.
+ */
+export function functionsTokenHeaderIsSigned(headerJson) {
+    return parsedTokenJson(headerJson, functionsTokenHeaderSchema) !== null;
+}
+/**
+ * Claim readers for an already signature-verified payload. They live beside the
+ * mint-side constants so the control plane's audiences and the host's required
+ * claims stay one definition rather than two that agree today.
+ */
+export function parseFunctionsDispatchTokenClaims(claimsJson) {
+    return parsedTokenJson(claimsJson, functionsDispatchTokenClaimsSchema);
+}
+export function parseFunctionsArtifactTokenClaims(claimsJson) {
+    return parsedTokenJson(claimsJson, functionsArtifactTokenClaimsSchema);
+}
 /**
  * Where invocation counts are reported, on the CONTROL PLANE rather than the
- * space origin.
- *
- * The two destinations are separate on purpose. Logs are the tenant's content
- * and stay on their own origin; usage is a number the platform bills from and
- * goes straight to us. Sharing one channel would make either destination a
- * plausible place to look for the other's data, and would put log volume on the
- * path that has to stay cheap.
+ * space origin. Logs are the tenant's content and stay on their own origin;
+ * usage is a number the platform bills from. One shared channel would put log
+ * volume on the path that has to stay cheap.
  */
 export const FUNCTIONS_USAGE_INTAKE_PATH = "/v1/runtime/functions/usage";
 /** Public, signed read path. Distinct from storage so the token is never a filename. */
 export const FUNCTIONS_BUNDLE_ROUTE_PREFIX = `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/b`;
 export const FUNCTIONS_RUNTIME_STORAGE_ROOT = "__spacefast/functions";
 /**
- * Where a version's compiled bundle lives.
- *
- * Under the same `__spacefast/` prefix as every other platform-owned path, so
- * there is one convention rather than one per product. Two consequences fall
- * out of that placement, and both are wanted:
- *
- * - It is not servable as static content. The runtime treats the whole prefix
- *   as control paths, so a tenant's compiled source is not readable at a
- *   guessable URL — and the digest that would make it guessable appears in
- *   build output.
- * - It is written by the ordinary publish path anyway. The upload policy
- *   carves out exactly this subtree (`publish-policy.ts`), so the bundle rides
- *   the normal manifest and upload passes instead of needing a parallel one.
- *
- * The dispatch configuration — host, capabilities, relay credential — is not
- * here and is not content at all. The engine writes it beside the version's
- * file tree rather than inside it, exactly as it does for Zero, so a publish
- * cannot reach it: no carve-out, no upload path, nothing to guard. A publish
- * able to write that file would be a publish able to grant itself authority it
- * was never given.
+ * Where a version's compiled bundle lives, under the same `__spacefast/` prefix
+ * as every other platform-owned path. Two consequences, both wanted:
+ *
+ * - Not servable as static content. The runtime treats the whole prefix as
+ *   control paths, so a tenant's compiled source is not readable at a guessable
+ *   URL, and the digest that would make it guessable appears in build output.
+ * - Written by the ordinary publish path. The upload policy carves out exactly
+ *   this subtree (`publish-policy.ts`), so the bundle rides the normal manifest
+ *   and upload passes.
+ *
+ * The dispatch configuration is not here and is not content at all. The engine
+ * writes it beside the version's file tree, as it does for Zero, so a publish
+ * cannot reach it and cannot grant itself authority it was never given.
  */
 export const FUNCTIONS_RUNTIME_BUNDLE_ROOT = `${FUNCTIONS_RUNTIME_STORAGE_ROOT}/bundles`;
 /**
- * Where a version's Next-cache seed document lives — the build-time prerender
- * and fetch-cache entries that warm the execution host's cache object so the
- * first visitor gets the page the build rendered instead of a live re-render.
- * A sibling of `bundles/` with the same properties: publishable through the
- * ordinary upload path (its own carve-out in publish-policy), never servable
- * as static content, read back only through the signed artifact route.
+ * Where a version's Next-cache seed document lives: the build-time prerender
+ * and fetch-cache entries that warm the execution host's cache object, so the
+ * first visitor gets the page the build rendered. A sibling of `bundles/` with
+ * the same properties, publishable through the ordinary upload path with its
+ * own carve-out in publish-policy, never servable as static content, read back
+ * only through the signed artifact route.
  */
 export const FUNCTIONS_RUNTIME_SEED_ROOT = `${FUNCTIONS_RUNTIME_STORAGE_ROOT}/seeds`;
 export const FUNCTIONS_BUNDLE_FORMAT = "spacefast.functions.bundle.v1";
 export const FUNCTIONS_SEED_FORMAT = "spacefast.functions.seed.v1";
 /**
- * Ceiling on a bundle's decoded size.
- *
- * The whole module graph arrives in one response so a cold isolate costs a
- * single round trip, which means this number is also how much the host holds in
- * memory before instantiating anything. Set below the runtime's own script
- * limit so an oversized build fails in our tooling, where we can say which
+ * Ceiling on a bundle's decoded size, and so on how much the host holds in
+ * memory before instantiating: the whole module graph arrives in one response,
+ * so a cold isolate costs a single round trip. Set below the runtime's own
+ * script limit, so an oversized build fails in our tooling, which can say which
  * modules are large, rather than at dispatch, where the tenant sees a 502.
  */
 export const FUNCTIONS_BUNDLE_MAX_BYTES = 8 * 1024 * 1024;
 /**
- * Ceilings on the cache seed document. Per-entry mirrors the cache object's
- * own row limit (an entry the object would refuse is dead weight in the
- * document); the total bounds what the host pulls and ingests on a cold
- * cache. Both are enforced in the CLI, where an overflow can say WHICH pages
- * were left out — an omitted entry is not an error, it just renders live on
- * first request like any cache miss.
+ * Ceilings on the cache seed document. Per-entry mirrors the cache object's own
+ * row limit; the total bounds what the host pulls and ingests on a cold cache.
+ * Both are enforced in the CLI, where an overflow can say WHICH pages were left
+ * out. An omitted entry renders live on first request like any cache miss.
  */
 export const FUNCTIONS_SEED_ENTRY_MAX_BYTES = 2 * 1024 * 1024 - 8192;
-// The Durable Object buffers the JSON once, then decoding/parsing temporarily
-// holds the text and object graph beside it. Keep the document far below
-// Cloudflare's 128 MiB SHARED-isolate ceiling; several objects can occupy that
-// isolate, and the host enforces this bound again while streaming the response.
+// Far below Cloudflare's 128 MiB SHARED-isolate ceiling: the Durable Object
+// buffers the JSON and holds the parsed graph beside it, and several objects can
+// occupy one isolate. The host enforces this bound again while streaming.
 export const FUNCTIONS_SEED_MAX_BYTES = 8 * 1024 * 1024;
 /**
- * One warm-cache entry: exactly what the runtime's incremental-cache client
- * would have written for `key` had it rendered the page itself. `valueJson`
- * is carried as the JSON string it already is on disk (OpenNext's `.cache` /
- * fetch-cache files) — re-parsing it here would only invite the seed writer
- * and the cache client to disagree about serialization.
+ * One warm-cache entry: what the runtime's incremental-cache client would have
+ * written for `key` had it rendered the page itself. `valueJson` stays the JSON
+ * string it already is on disk (OpenNext's `.cache` / fetch-cache files), so the
+ * seed writer and the cache client cannot disagree about serialization.
  */
 export const functionsSeedEntrySchema = z
     .object({
@@ -165,25 +224,20 @@ const functionsRoutePathSchema = appRoutePathSchema({
     subject: "Function routes",
 });
 /**
- * How many entries the origin's dispatch table accepts.
- *
- * Exported because the CLI classifier has to compact its route claims BEFORE
- * assembling the artifact — discovering the ceiling as a validation error at
- * finalize would mean a build that classified fine fails at the last step — so
- * the ceiling has to be a value both sides can read, not a literal each side
- * spells for itself.
+ * How many entries the origin's dispatch table accepts. Exported because the CLI
+ * classifier compacts its route claims BEFORE assembling the artifact: meeting
+ * the ceiling as a finalize error would fail a build that classified fine.
  */
 export const FUNCTIONS_MAX_ROUTES = 256;
 /**
- * A worker's dynamic route table. Anything not matched here is answered from
- * the version's static content by wp.cloud and never reaches Cloudflare, which
- * is both the cheaper path and the one that keeps assets ours.
+ * A worker's dynamic route table. Anything not matched here is answered from the
+ * version's static content by wp.cloud and never reaches Cloudflare.
  *
  * A `subtree` entry covers its own path AND everything below it: the engine
  * expands one into both `path` and `path/:splat`
- * (`_stattic_runtime_functions_routes_artifact`, runtime/engine/admin/management.php),
- * which is why `wholeSiteRoutes()` is a single `/` subtree entry and why an
- * exact entry beside a subtree entry at the same path is dead weight.
+ * (`_stattic_runtime_functions_routes_artifact`, runtime/engine/admin/management.php).
+ * So `wholeSiteRoutes()` is a single `/` subtree entry, and an exact entry beside
+ * a subtree entry at the same path is dead weight.
  */
 export const functionsRouteSchema = z
     .object({
@@ -210,12 +264,9 @@ export const functionsBundleModuleSchema = z.union([
     z.object({ data: executionBase64Schema }).strict(),
 ]);
 /**
- * The document served at a bundle URL and parsed by the host.
- *
- * Both sides of that exchange validate against this schema, which is the point
- * of it living here: the CLI's bundler and the host's loader are separate
- * deployments that must agree, and the only thing keeping them honest is a
- * shared definition of the bytes in between.
+ * The document served at a bundle URL and parsed by the host. The CLI's bundler
+ * and the host's loader are separate deployments, and this shared definition is
+ * the only thing keeping them agreed on the bytes in between.
  */
 export const functionsBundleManifestSchema = z
     .object({
@@ -230,10 +281,9 @@ export const functionsBundleManifestSchema = z
 });
 /**
  * Where the worker's compiled bytes live in the version's own content store.
- * Unlike Zero's bundles these are not carried inline in the finalize payload:
- * framework output routinely runs to megabytes, and inlining it would put the
- * whole thing through the control plane, which the direct-from-wp.cloud rule
- * forbids.
+ * Not inline in the finalize payload like Zero's bundles: framework output runs
+ * to megabytes, and inlining it would push the whole thing through the control
+ * plane, which the direct-from-wp.cloud rule forbids.
  */
 export const functionsBundleRefSchema = z
     .object({
@@ -249,9 +299,9 @@ export const functionsBundleRefSchema = z
 })
     .strict();
 /**
- * Where a version's cache seed document sits in its content store — the
- * bundle ref's sibling, with the seed's own root and ceiling. `entries` is
- * carried so status surfaces can say what the seed holds without fetching it.
+ * Where a version's cache seed document sits in its content store, the bundle
+ * ref's sibling with the seed's own root and ceiling. `entries` is carried so
+ * status surfaces can say what the seed holds without fetching it.
  */
 export const functionsSeedRefSchema = z
     .object({
@@ -268,39 +318,34 @@ export const functionsSeedRefSchema = z
 })
     .strict();
 /**
- * The path a bundle is served from.
- *
- * Content-addressed, so the response is immutable and can be cached at our edge
- * forever — a cold isolate anywhere in the world costs one CDN hit rather than
- * a round trip to the space's origin.
- *
- * The token rides in the path rather than the query string for exactly that
- * reason: a query parameter is subject to cache-key normalisation, and a token
- * that gets stripped from the key would let one space's cached bundle answer
- * another space's URL.
- *
- * Both halves are load-bearing. The digest alone is unguessable to anyone who
- * lacks the bytes, but it is derivable by anyone who *has* them, and it shows up
- * in build output and `sf runtime status`. The token adds the dimension the
- * digest cannot: holding the code does not entitle you to fetch it from us, and
- * rotating the site secret invalidates every URL at once.
+ * The path a bundle is served from. Content-addressed, so the response is
+ * immutable and cacheable at our edge forever: a cold isolate anywhere costs one
+ * CDN hit rather than a round trip to the space's origin.
+ *
+ * The token rides in the path rather than the query string for the same reason.
+ * A query parameter is subject to cache-key normalisation, and a token stripped
+ * from the key would let one space's cached bundle answer another space's URL.
+ *
+ * Both halves are load-bearing. The digest is derivable by anyone holding the
+ * bytes and shows up in build output and `sf runtime status`. The token adds
+ * what the digest cannot: holding the code does not entitle you to fetch it from
+ * us, and rotating the site secret invalidates every URL at once.
  */
 export function functionsBundlePath(input) {
     return `${FUNCTIONS_BUNDLE_ROUTE_PREFIX}/${bundleDigest(input.sha256)}/${input.token}/bundle.json`;
 }
 /**
- * The seed document's read path — the bundle route with a different terminal
- * filename and its own token audience. One signed artifact route on the
- * origin serves both: the filename says what the digest names, the token's
- * audience says what the caller was authorised to read.
+ * The seed document's read path: the bundle route with a different terminal
+ * filename and its own token audience. One signed artifact route on the origin
+ * serves both.
  */
 export function functionsSeedPath(input) {
     return `${FUNCTIONS_BUNDLE_ROUTE_PREFIX}/${bundleDigest(input.sha256)}/${input.token}/seed.json`;
 }
 /**
- * Where the bundle actually sits in the published version — the same path minus
- * the token segment. The token authorises the read; it does not name the file,
- * so rotating the signing key changes every URL without moving a single byte.
+ * Where the bundle sits in the published version, the same path minus the token
+ * segment. The token authorises the read; it does not name the file, so rotating
+ * the signing key changes every URL without moving a byte.
  */
 export function functionsBundleStoragePath(input) {
     return `${FUNCTIONS_RUNTIME_BUNDLE_ROOT}/${bundleDigest(input.sha256)}/bundle.json`;
@@ -311,17 +356,16 @@ export function functionsSeedStoragePath(input) {
 }
 /**
  * The digest is carried in contracts as `sha256:<hex>` but appears in paths as
- * bare hex: a colon is legal in a path segment yet needlessly invites
- * normalisation differences between the edge, the origin, and fetch.
+ * bare hex: a colon in a path segment invites normalisation differences between
+ * the edge, the origin, and fetch.
  */
 function bundleDigest(sha256) {
     return sha256.startsWith("sha256:") ? sha256.slice(7) : sha256;
 }
 /**
- * Cloudflare pins runtime behaviour to a date rather than a version number, so
- * a worker built today keeps today's semantics forever. We record the author's
- * choice on the version, which is what makes rollback honest: promoting an old
- * version restores the compatibility date it was built against.
+ * Cloudflare pins runtime behaviour to a date rather than a version number, so a
+ * worker built today keeps today's semantics forever. Recorded on the version,
+ * so promoting an old version restores the date it was built against.
  */
 const functionsCompatibilityDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
 export const functionsWorkerArtifactSchema = z
@@ -330,23 +374,22 @@ export const functionsWorkerArtifactSchema = z
     appName: z.string().min(1).max(128),
     /**
      * What the author wrote, for display: `handler.ts`, `.open-next/worker.js`.
-     * It names a file in their project, which after bundling no longer exists.
+     * The file no longer exists after bundling.
      */
     entry: z.string().min(1).max(1024),
     /**
-     * The entry module's name *inside the bundle manifest* — what the loader
-     * instantiates. Carried here rather than read from the manifest because the
-     * origin dispatches without ever opening the bundle: the bytes go from our
-     * CDN straight to the isolate, and the origin only routes.
+     * The entry module's name *inside the bundle manifest*, which is what the
+     * loader instantiates. Carried here rather than read from the manifest
+     * because the origin dispatches without opening the bundle: the bytes go
+     * from our CDN straight to the isolate.
      */
     mainModule: z.string().min(1).max(1024),
     bundle: functionsBundleRefSchema,
     /**
-     * The build-time cache seed, or null when the build produced nothing
-     * worth warming (no prerenders left with the worker, no fetch cache).
-     * A ref, not content: the document rides the version's own file tree
-     * like the bundle, and the host pulls it through a signed URL minted at
-     * finalize.
+     * The build-time cache seed, or null when the build produced nothing worth
+     * warming. A ref, not content: the document rides the version's own file
+     * tree like the bundle, and the host pulls it through a signed URL minted
+     * at finalize.
      */
     seed: functionsSeedRefSchema.nullable().default(null),
     compatibilityDate: functionsCompatibilityDateSchema,
@@ -354,25 +397,24 @@ export const functionsWorkerArtifactSchema = z
     routes: z.array(functionsRouteSchema).max(FUNCTIONS_MAX_ROUTES).default([]),
     /**
      * Cookie names whose presence must skip the origin's static fast path on
-     * claimed routes — the framework's draft/preview session markers. Data
-     * from the classifier, not names the engine knows: the origin checks the
-     * Cookie header against this list and dispatches instead of serving the
-     * extracted file, which is what lets a fully-static page still honor a
-     * draft session without a build-wide draft-usage proof.
+     * claimed routes, the framework's draft/preview session markers. Data from
+     * the classifier, not names the engine knows: the origin checks the Cookie
+     * header against this list and dispatches instead of serving the extracted
+     * file, which lets a fully-static page honor a draft session.
      */
     bypassCookies: z.array(z.string().min(1).max(128)).max(8).default([]),
     /**
-     * Aggregate of what the worker's handlers reach, used to decide which
-     * brokered capabilities the relay will honour for this version. A worker
-     * that never declares `db` gets a relay that refuses `db.read` outright,
-     * so an injected dependency cannot widen authority at runtime.
+     * Aggregate of what the worker's handlers reach, deciding which brokered
+     * capabilities the relay honours for this version. A worker that never
+     * declares `db` gets a relay that refuses `db.read` outright, so an injected
+     * dependency cannot widen authority at runtime.
      */
     capabilities: executionCapabilitiesSchema,
     /**
-     * Platform-owned runtime services this build needs. This is deliberately
-     * separate from author capabilities: an OpenNext build needs durable cache
-     * storage even when the application itself declares no database or fetch
-     * access, and that storage must never become a general tenant credential.
+     * Platform-owned runtime services this build needs, separate from author
+     * capabilities: an OpenNext build needs durable cache storage even when the
+     * application declares no database or fetch access, and that storage must
+     * never become a general tenant credential.
      */
     platform: z
         .object({
@@ -384,12 +426,10 @@ export const functionsWorkerArtifactSchema = z
     .strict();
 /**
  * The authority a dispatched worker may exercise, in the vocabulary the host
- * speaks on the wire.
- *
- * Deliberately a different, narrower list than `executionCapabilitiesSchema`.
- * That one records what a build *declared* it uses; this one is what the origin
- * *grants*, resolved by the control plane at finalize so the origin forwards a
- * decision rather than making one. Anything absent fails closed at the relay.
+ * speaks on the wire. Narrower than `executionCapabilitiesSchema`, which records
+ * what a build *declared* it uses; this is what the origin *grants*, resolved by
+ * the control plane at finalize so the origin forwards a decision rather than
+ * making one. Anything absent fails closed at the relay.
  */
 export const FUNCTIONS_DISPATCH_CAPABILITIES = [
     "storage.read",
@@ -407,29 +447,22 @@ export const functionsDispatchCapabilitySchema = z.enum(FUNCTIONS_DISPATCH_CAPAB
 /**
  * Resolves a build's declared capabilities into the grant a dispatch carries.
  *
- * Three declared capabilities have no dispatch counterpart, each for its own
- * reason:
+ * Three declared capabilities have no dispatch counterpart:
  *
  * - `env` is not a runtime call at all. Values are resolved at finalize and
  *   travel in the config, so a worker reading `env` reaches nothing.
- * - `auth` and `realtime` bind a handler to the local tier — see
- *   `endpointIsPortable` — so code declaring them deploys as a capsule and
- *   never arrives here.
- *
- * `db` widens to both read and write because a declaration says a handler
- * touches the database, not how. Narrowing it would take per-statement analysis
- * we do not do, and guessing "read-only" from a declaration would be a grant
- * the author never asked for and cannot see.
+ * - `auth` and `realtime` bind a handler to the local tier, so code declaring
+ *   them deploys as a capsule and never arrives here. See `endpointIsPortable`.
  *
- * The three platform-service grants are named for the operation an author
- * reaches for, and each covers its service's whole operation set for the same
- * reason `db` widens: a declaration says a handler uses spam checking, not that
- * it never files a correction.
+ * `db` widens to both read and write, and each platform-service grant covers its
+ * service's whole operation set, because a declaration says a handler touches
+ * the database or checks for spam, not how. Narrowing would take per-statement
+ * analysis we do not do.
  */
 export function functionsDispatchCapabilities(capabilities, platform = {}) {
-    // Storage is the durable, unversioned substrate every app receives. It is a
-    // base binding like the Zero client's `storage`, not a source-declared
-    // capability that disappears when a new version omits an import.
+    // Storage is a base binding every app receives, like the Zero client's
+    // `storage`, not a source-declared capability that disappears when a new
+    // version omits an import.
     const granted = new Set(["storage.read", "storage.write"]);
     if (capabilities.db) {
         granted.add("db.read");
@@ -454,8 +487,7 @@ export function functionsDispatchCapabilities(capabilities, platform = {}) {
         granted.add("next.cache");
     }
     // Filtered from the canonical list so the order is stable: the grant is part
-    // of the host's isolate identity, and a reordering would retire warm isolates
-    // for no reason.
+    // of the host's isolate identity, and reordering would retire warm isolates.
     return FUNCTIONS_DISPATCH_CAPABILITIES.filter((capability) => granted.has(capability));
 }
 /** Logs and the host-local Next cache do not transit the origin relay. */
@@ -463,12 +495,11 @@ export function functionsGrantNeedsRelay(granted) {
     return granted.some((capability) => capability !== "log" && capability !== "next.cache");
 }
 /**
- * What the space origin needs in order to dispatch to the host on its own. The
- * shared secret is a wp.cloud site secret; it is never part of a version's
- * content and never reaches tenant code, so it is not modelled here.
- *
- * There is no account id and no namespace: the origin talks to one host worker
- * over HTTPS and holds no Cloudflare API credential at all.
+ * What the space origin needs to dispatch to the host on its own. The shared
+ * secret is a wp.cloud site secret, never part of a version's content and never
+ * reachable by tenant code, so it is not modelled here. There is no account id
+ * and no namespace: the origin talks to one host worker over HTTPS and holds no
+ * Cloudflare API credential.
  */
 export const functionsHostConfigSchema = z
     .object({
@@ -479,7 +510,7 @@ export const functionsHostConfigSchema = z
      * finalize.
      *
      * It is here rather than on the artifact because the artifact records what
-     * was built — a path and a digest, both stable — while this records how to
+     * was built, meaning a path and a digest, both stable. This records how to
      * reach it, which depends on a signing key and a hostname the build knew
      * nothing about. Rotating the key changes every URL without changing a
      * single artifact.
@@ -487,9 +518,9 @@ export const functionsHostConfigSchema = z
     bundleUrl: z.string().url(),
     /**
      * Where the host pulls the version's cache seed, minted beside the bundle
-     * URL for the same reasons — null exactly when the artifact carries no
-     * seed. The host folds it into the cache object's cold-start path, never
-     * into request serving: an unreachable seed is a cold cache, not an error.
+     * URL and null exactly when the artifact carries no seed. It feeds the cache
+     * object's cold-start path, never request serving: an unreachable seed is a
+     * cold cache, not an error.
      */
     seedUrl: z.string().url().nullable().default(null),
 })
@@ -497,21 +528,18 @@ export const functionsHostConfigSchema = z
 /**
  * The callback a dispatched worker uses for `ctx.db`, `ctx.fetch` and logging.
  *
- * Each relay call re-enters the space's PHP-FPM pool, which is the deadlock
- * hazard this product's admission control exists to bound: a proxied request
- * occupies a worker for its whole life while its relay calls demand more. The
- * batching allowance below is the other half of the answer — a handler that
- * issues twenty statements must cost one relay round trip, not twenty. Measured
- * against the PHP broker, batching twenty writes into one call is 8.3x faster
- * than twenty separate ones.
+ * Each relay call re-enters the space's PHP-FPM pool, the deadlock hazard this
+ * product's admission control bounds: a proxied request occupies a worker for
+ * its whole life while its relay calls demand more. Batching is the other half.
+ * Against the PHP broker, twenty writes in one call is 8.3x faster than twenty
+ * separate ones.
  */
 export const functionsRelayConfigSchema = z
     .object({
     url: z.string().url(),
     /**
-     * Bearer credential minted per version. Rotating it also retires the warm
-     * isolate holding it: the host folds this token into the isolate's identity
-     * precisely so that a revoked credential cannot outlive its revocation.
+     * Bearer credential minted per version. The host folds it into the warm
+     * isolate's identity, so rotating it retires the isolate holding it.
      */
     token: z.string().min(1),
     maxBatchStatements: z.number().int().min(1).max(256),
@@ -519,21 +547,18 @@ export const functionsRelayConfigSchema = z
 })
     .strict();
 /**
- * Where the execution host reports how much this version ran.
- *
- * Absent means uncounted, not refused: a space whose configuration predates
- * usage reporting must keep serving, and an execution tier that cannot reach
- * the control plane must never fail a request over it. Counting is reporting
- * only — nothing here throttles, and no limit is enforced anywhere from it.
+ * Where the execution host reports how much this version ran. Absent means
+ * uncounted, not refused: a space whose configuration predates usage reporting
+ * must keep serving, and a tier that cannot reach the control plane must never
+ * fail a request over it. Nothing here throttles.
  */
 export const functionsUsageConfigSchema = z
     .object({
     url: z.string().url(),
     /**
      * Minted and verified by the control plane alone; the space only forwards
-     * it. Version-scoped like the relay credential, and folded into the host's
-     * isolate identity for the same reason: a rotated credential must not
-     * outlive its rotation inside a warm isolate.
+     * it. Version-scoped and folded into the isolate identity like the relay
+     * credential, so a rotated credential cannot outlive its rotation.
      */
     token: z.string().min(1),
 })
@@ -542,13 +567,11 @@ export const functionsUsageConfigSchema = z
  * The credential the execution host presents at the origin's purge route.
  *
  * Only the token lives here: the purge route is on whichever hostname the
- * visitor actually hit, so the origin composes the URL from the request host at
- * dispatch time — exactly as it does for log intake — instead of freezing one
- * hostname at finalize. A third credential rather than a reuse of the relay's,
- * for the relay's own reason: purging cached responses is a distinct authority,
- * and a worker whose relay is unusable must still be able to invalidate what it
- * rendered. Version-scoped and folded into the host's isolate identity like its
- * siblings, so a republish revokes it.
+ * visitor hit, so the origin composes the URL from the request host at dispatch
+ * time rather than freezing one hostname at finalize. A third credential rather
+ * than a reuse of the relay's, because a worker whose relay is unusable must
+ * still be able to invalidate what it rendered. Version-scoped, so a republish
+ * revokes it.
  */
 export const functionsPurgeConfigSchema = z
     .object({
@@ -556,15 +579,14 @@ export const functionsPurgeConfigSchema = z
 })
     .strict();
 /**
- * What a build declares about its worker — everything the CLI can know from the
+ * What a build declares about its worker, everything the CLI can know from the
  * author's project alone.
  *
- * Unlike Zero, this is *not* the same document the runtime receives. A build
- * cannot name the host it will be dispatched to, cannot mint the credential its
- * relay calls will carry, and cannot decide what authority it is granted; all
- * three are the platform's to say. Keeping them out of this schema is what makes
- * that structural rather than a convention — a version's own metadata has no
- * field in which to assert authority it was not given.
+ * Unlike Zero, this is *not* the document the runtime receives. A build cannot
+ * name the host it is dispatched to, mint the credential its relay calls carry,
+ * or decide what authority it is granted. Keeping all three out of this schema
+ * leaves a version's own metadata no field in which to assert authority it was
+ * not given.
  */
 export const functionsSourceFinalizeSchema = z
     .object({
@@ -583,10 +605,9 @@ export const functionsSourceFinalizeSchema = z
  * The document the control plane sends to the runtime, which the engine stores
  * beside the version's files and the origin reads on every dispatch.
  *
- * It is the build's declaration plus the things only the platform can supply:
- * where to dispatch, what the worker is allowed to do, the credentials that let
- * it do those things and report what it did, and the resolved values of its
- * variables.
+ * It is the build's declaration plus what only the platform can supply: where to
+ * dispatch, what the worker may do, the credentials for doing and reporting it,
+ * and the resolved variable values.
  */
 export const functionsRuntimeConfigSchema = functionsSourceFinalizeSchema
     .extend({
@@ -597,7 +618,7 @@ export const functionsRuntimeConfigSchema = functionsSourceFinalizeSchema
     purge: functionsPurgeConfigSchema.nullable().default(null),
     /**
      * Resolved at finalize, so a worker reading configuration never calls back
-     * to us for it — and so rotating a variable is a republish with an audit
+     * to us for it, and so rotating a variable is a republish with an audit
      * trail rather than a live mutation of what running code sees.
      */
     variableValues: z.record(z.string(), z.string()).default({}),
@@ -614,11 +635,9 @@ export const functionsDeployMetadataSchema = z
 })
     .strict();
 /**
- * Builds the declaration a publish attaches to its version.
- *
- * Exists so the CLI's publish step and every test that needs a Functions
- * version agree on the shape by construction rather than by copying an object
- * literal around — the same reason `createZeroRuntimeFinalizePayload` exists.
+ * Builds the declaration a publish attaches to its version, so the CLI's publish
+ * step and every test needing a Functions version agree on the shape by
+ * construction. Mirrors `createZeroRuntimeFinalizePayload`.
  */
 export function createFunctionsSourceFinalize(input) {
     return functionsSourceFinalizeSchema.parse({
@@ -645,12 +664,9 @@ export function createFunctionsSourceFinalize(input) {
 }
 /**
  * What a version's worker is currently doing, as an observer of the space can
- * actually determine.
- *
- * There is no upload state to report. A bundle is either in the version's
- * content store or it is not, and dispatch is decided by which version is
- * serving — so these three cover the whole space of answers, and each one is
- * checkable rather than inferred from a job we ran earlier.
+ * determine. There is no upload state: a bundle is either in the version's
+ * content store or it is not, and dispatch follows whichever version is serving,
+ * so each of these three is checkable rather than inferred from an earlier job.
  */
 export const functionsExecutionStateSchema = z.enum([
     /** No bundle at the version's bundle path. */
@@ -663,17 +679,14 @@ export const functionsExecutionStateSchema = z.enum([
 /**
  * What a live worker is, as the `worker` member of a space's runtime status.
  *
- * It carries no kind tag. The member it rides in already says which product
- * answered, and the same tree can carry a capsule beside it — a discriminant
- * here could only repeat the field name or contradict its sibling.
- *
- * No `versionId`: the status response it rides in already names the live
- * version.
+ * No kind tag: the member it rides in already says which product answered, and
+ * the same tree can carry a capsule beside it. No `versionId`: the status
+ * response already names the live version. No `database` field:
+ * `capabilities.db` is the fact the whole `/db` family branches on, and stating
+ * it twice invites the two to disagree.
  *
- * Everything but `executionState` is a field of the version's own finalize
- * metadata, so this answers whether or not the origin is reachable. There is no
- * `database` field: `capabilities.db` is the fact the whole `/db` family
- * branches on, and stating it twice invites the two to disagree.
+ * Everything but `executionState` comes from the version's finalize metadata, so
+ * this answers whether or not the origin is reachable.
  */
 export const functionsAppSchema = z
     .object({