next-evolve 0.0.0-stage → 0.3.1

package/dist/server/sync-route.js

@@ -0,0 +1,100 @@
+import { logRateLimited } from "../core/log.js";
+import { sharedReplayGuard } from "./aggregate-route.js";
+import { DELIVERY_HEADER, SIGNATURE_HEADER, SUPPORTED_PROTOCOLS, isSupportedProtocol, parseSecretKey, syncWebhookSchema, unsupportedProtocolBody, verifyBody } from "@next-evolve/protocol";
+// src/server/sync-route.ts
+/** Cache tag on the render-side bundle fetch (spec §7.7). */
+const BUNDLE_TAG = "evolve-bundle";
+/** At most one refresh per window. */
+const SYNC_MIN_INTERVAL_MS = 5e3;
+const MAX_BODY_BYTES = 16384;
+const createSyncThrottle = () => ({
+	last: -Infinity,
+	waiting: null
+});
+const THROTTLE = Symbol.for("next-evolve.sync-throttle");
+function sharedThrottle() {
+	const g = globalThis;
+	g[THROTTLE] ??= createSyncThrottle();
+	return g[THROTTLE];
+}
+const json = (status, body) => Response.json(body, { status });
+async function handleSync(req, deps) {
+	const secret = deps.env.EVOLVE_WEBHOOK_SECRET;
+	const site = parseSecretKey(deps.env.EVOLVE_SECRET_KEY ?? "")?.siteId;
+	const store = deps.store();
+	if (!secret || !site || !store) return json(503, { error: "not_configured" });
+	const body = await req.text();
+	if (Buffer.byteLength(body) > MAX_BODY_BYTES) return json(413, { error: "too_large" });
+	const now = deps.now ?? Date.now;
+	const sig = verifyBody(req.headers.get(SIGNATURE_HEADER), body, secret, { now: Math.floor(now() / 1e3) });
+	if (!sig.ok) return json(401, {
+		error: "invalid_signature",
+		reason: sig.reason
+	});
+	if (!(deps.replay ?? sharedReplayGuard()).check(req.headers.get(DELIVERY_HEADER) ?? "")) return json(409, { error: "replayed" });
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return json(400, { error: "invalid_json" });
+	}
+	if (!isSupportedProtocol(parsed?.pv)) return json(400, unsupportedProtocolBody());
+	const r = syncWebhookSchema.safeParse(parsed);
+	if (!r.success) return json(400, { error: "invalid" });
+	const current = store.current();
+	if (r.data.type === "ping") return json(202, {
+		ok: true,
+		ver: current?.ver ?? null,
+		protocol: { supported: SUPPORTED_PROTOCOLS }
+	});
+	if (r.data.site !== site) return json(403, { error: "site_mismatch" });
+	if (!(!current || r.data.ver > current.ver || r.data.ver === current.ver && r.data.iat > current.iat)) return json(202, {
+		accepted: false,
+		reason: "current"
+	});
+	const work = () => throttledRefresh(store, deps);
+	(deps.defer ?? deferAfter)(work);
+	return json(202, { accepted: true });
+}
+/**
+* Refreshes at most once per {@link SYNC_MIN_INTERVAL_MS}. A call inside the
+* window waits for its end (calls that arrive meanwhile share that refresh),
+* so the last change is always pulled.
+*/
+function throttledRefresh(store, deps) {
+	const t = deps.throttle ?? sharedThrottle();
+	if (t.waiting) return t.waiting;
+	const now = deps.now ?? Date.now;
+	const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const wait = Math.max(0, t.last + SYNC_MIN_INTERVAL_MS - now());
+	const run = async () => {
+		if (wait > 0) await sleep(wait);
+		t.waiting = null;
+		t.last = now();
+		const before = store.token();
+		await store.refresh({ force: true });
+		const after = store.token();
+		if (after && after !== before) await (deps.onSynced ?? revalidateBundle)(after);
+	};
+	const p = run().catch((e) => logRateLimited("sync", "sync refresh failed", e));
+	t.waiting = wait > 0 ? p : null;
+	return p;
+}
+async function deferAfter(task) {
+	try {
+		const { after } = await import("next/server");
+		after(task);
+	} catch {
+		task();
+	}
+}
+/** Drops cached render-side bundle fetches (and pages that used them). */
+async function revalidateBundle() {
+	try {
+		const { revalidateTag } = await import("next/cache");
+		revalidateTag(BUNDLE_TAG, { expire: 0 });
+	} catch (e) {
+		logRateLimited("sync:revalidate", "revalidateTag failed", e);
+	}
+}
+export { BUNDLE_TAG, SYNC_MIN_INTERVAL_MS, createSyncThrottle, handleSync, revalidateBundle };

package/dist/server/track-route.d.ts

@@ -0,0 +1,25 @@
+import { Goals } from "../config/goals.js";
+import { Writer } from "../db/writer.js";
+import { z } from "zod";
+export declare const MAX_TRACK_EVENTS = 500;
+export declare const trackBodySchema: z.ZodObject<{
+  events: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    anonId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    props: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    source: z.ZodOptional<z.ZodString>;
+    ts: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    dedupeKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * `POST /api/evolve/track`: server-to-server events (Segment, a CRM, a
+ * webhook relay) with `Authorization: Bearer $EVOLVE_TRACK_SECRET`.
+ */
+export declare function handleTrack(req: Request, deps: {
+  secret: string | undefined;
+  goals: Goals | undefined;
+  writer: Writer;
+}): Promise<Response>;

package/dist/server/track-route.js

@@ -0,0 +1,49 @@
+import { eventRow } from "./events.js";
+import { z } from "zod";
+import { timingSafeEqual } from "node:crypto";
+// src/server/track-route.ts
+const MAX_TRACK_EVENTS = 500;
+const trackEvent = z.object({
+	name: z.string().min(1).max(100),
+	userId: z.string().max(256).nullish(),
+	anonId: z.string().max(64).nullish(),
+	value: z.number().finite().nullish(),
+	props: z.record(z.string(), z.unknown()).nullish(),
+	source: z.string().max(64).optional(),
+	ts: z.union([z.string(), z.number()]).optional(),
+	dedupeKey: z.string().max(200).nullish()
+});
+const trackBodySchema = z.object({ events: z.array(trackEvent).min(1).max(500) });
+function bearerOk(req, secret) {
+	const h = req.headers.get("authorization") ?? "";
+	const got = Buffer.from(h.startsWith("Bearer ") ? h.slice(7) : "");
+	const want = Buffer.from(secret);
+	return got.length === want.length && timingSafeEqual(got, want);
+}
+/**
+* `POST /api/evolve/track`: server-to-server events (Segment, a CRM, a
+* webhook relay) with `Authorization: Bearer $EVOLVE_TRACK_SECRET`.
+*/
+async function handleTrack(req, deps) {
+	if (!deps.secret) return Response.json({ error: "track_disabled" }, { status: 404 });
+	if (!bearerOk(req, deps.secret)) return Response.json({ error: "unauthorized" }, { status: 401 });
+	let body;
+	try {
+		const r = trackBodySchema.safeParse(await req.json());
+		if (!r.success) return Response.json({
+			error: "invalid_body",
+			issues: r.error.issues.slice(0, 5)
+		}, { status: 400 });
+		body = r.data;
+	} catch {
+		return Response.json({ error: "invalid_json" }, { status: 400 });
+	}
+	const rows = body.events.flatMap((e) => {
+		const row = eventRow(e.name, e, deps.goals, "webhook");
+		return row ? [row] : [];
+	});
+	deps.writer.events(rows);
+	await deps.writer.flush();
+	return Response.json({ accepted: rows.length });
+}
+export { MAX_TRACK_EVENTS, handleTrack, trackBodySchema };

package/dist/store/disk.d.ts

@@ -0,0 +1,6 @@
+export declare const defaultDiskDir: () => string;
+export declare const diskPath: (dir: string, site: string) => string;
+/** The cached token, or null (missing or unreadable). */
+export declare function readDisk(path: string): string | null;
+/** Atomic write (temp file + rename). Never throws. */
+export declare function writeDisk(path: string, token: string): void;

package/dist/store/disk.js

@@ -0,0 +1,23 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// src/store/disk.ts
+const defaultDiskDir = () => tmpdir();
+const diskPath = (dir, site) => join(dir, `evolve-${site}.jws`);
+/** The cached token, or null (missing or unreadable). */
+function readDisk(path) {
+	try {
+		return readFileSync(path, "utf8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+/** Atomic write (temp file + rename). Never throws. */
+function writeDisk(path, token) {
+	const tmp = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(tmp, token, { mode: 384 });
+		renameSync(tmp, path);
+	} catch {}
+}
+export { defaultDiskDir, diskPath, readDisk, writeDisk };

package/dist/store/fetch.d.ts

@@ -0,0 +1,26 @@
+export type FetchBundleResult = {
+  status: "ok";
+  token: string;
+  etag: string | null;
+} | {
+  status: "not_modified";
+} | {
+  status: "error";
+  code: number | "network";
+  message?: string;
+};
+/**
+ * `GET {cloud}/v1/bundle` with the secret key and `If-None-Match` (spec §7.5).
+ * Never throws. Verification is the caller's job.
+ *
+ * Uses node:http(s) unless a `fetch` is injected (tests): the render path
+ * refreshes through this too, and inside a static (ISR) render Next's patched
+ * `fetch` turns an uncached call into "dynamic usage" and fails the page.
+ */
+export declare function fetchBundle(opts: {
+  cloudUrl: string;
+  secretKey: string;
+  etag?: string | null;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}): Promise<FetchBundleResult>;

package/dist/store/fetch.js

@@ -0,0 +1,74 @@
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+// src/store/fetch.ts
+/**
+* `GET {cloud}/v1/bundle` with the secret key and `If-None-Match` (spec §7.5).
+* Never throws. Verification is the caller's job.
+*
+* Uses node:http(s) unless a `fetch` is injected (tests): the render path
+* refreshes through this too, and inside a static (ISR) render Next's patched
+* `fetch` turns an uncached call into "dynamic usage" and fails the page.
+*/
+async function fetchBundle(opts) {
+	const f = opts.fetch ?? httpFetch;
+	try {
+		const res = await f(new URL("/v1/bundle", opts.cloudUrl), {
+			headers: {
+				authorization: `Bearer ${opts.secretKey}`,
+				...opts.etag ? { "if-none-match": opts.etag } : {}
+			},
+			cache: "no-store",
+			signal: AbortSignal.timeout(opts.timeoutMs ?? 5e3)
+		});
+		if (res.status === 304) return { status: "not_modified" };
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			return {
+				status: "error",
+				code: res.status,
+				message: body.slice(0, 200)
+			};
+		}
+		return {
+			status: "ok",
+			token: (await res.text()).trim(),
+			etag: res.headers.get("etag")
+		};
+	} catch (e) {
+		return {
+			status: "error",
+			code: "network",
+			message: String(e)
+		};
+	}
+}
+/** A tiny GET over node:http(s) with fetch's shape (the parts fetchBundle uses). */
+function httpFetch(url, init) {
+	return new Promise((resolve, reject) => {
+		const req = (url.protocol === "https:" ? request$1 : request)(url, {
+			method: "GET",
+			headers: init.headers,
+			signal: init.signal
+		}, (res) => {
+			const chunks = [];
+			res.on("data", (c) => chunks.push(c));
+			res.on("error", reject);
+			res.on("end", () => {
+				const status = res.statusCode ?? 0;
+				const body = Buffer.concat(chunks).toString("utf8");
+				resolve({
+					status,
+					ok: status >= 200 && status < 300,
+					text: async () => body,
+					headers: { get: (n) => {
+						const v = res.headers[n.toLowerCase()];
+						return Array.isArray(v) ? v[0] ?? null : v ?? null;
+					} }
+				});
+			});
+		});
+		req.on("error", reject);
+		req.end();
+	});
+}
+export { fetchBundle };

package/dist/store/global-config.d.ts

@@ -0,0 +1,39 @@
+import { FetchBundleResult } from "./fetch.js";
+type Env = Record<string, string | undefined>;
+/** How often instances re-read Global Config. */
+export declare const GLOBAL_CONFIG_TTL_MS = 10000;
+/** Max wait for the first read on a cold start; then the build bundle serves. */
+export declare const COLD_READ_CAP_MS = 20;
+export declare const globalConfigItemKey: (site: string) => string;
+export type GlobalConfigSettings = {
+  connectionString: string;
+  /** Write access (sync route only). */
+  id?: string;
+  apiToken?: string;
+  teamId?: string;
+};
+/**
+ * Global Config settings when the app opted in: `store: "global-config"`, or
+ * `"auto"` with `EVOLVE_GLOBAL_CONFIG` (connection string) set.
+ */
+export declare function globalConfigSettings(store: "auto" | "memory" | "global-config" | undefined, env: Env): GlobalConfigSettings | null;
+export type GlobalConfigReader = (key: string) => Promise<unknown>;
+export declare function defaultReader(connectionString: string): GlobalConfigReader;
+/**
+ * Fetcher for the memory store: reads Global Config every call; also asks the
+ * cloud when Global Config is empty or every `cloudEveryMs` (so a missed
+ * webhook or a stale item can't freeze the app), and returns the newer token.
+ */
+export declare function createGlobalConfigFetcher(opts: {
+  site: string;
+  read: GlobalConfigReader;
+  cloud?: (etag: string | null) => Promise<FetchBundleResult>;
+  cloudEveryMs: number;
+  now?: () => number;
+}): (etag: string | null) => Promise<FetchBundleResult>;
+/**
+ * Writes the token to the site's item via the Vercel REST API (sync route).
+ * Never throws; returns whether the write succeeded.
+ */
+export declare function writeGlobalConfig(settings: GlobalConfigSettings, site: string, token: string, f?: typeof fetch): Promise<boolean>;
+export {};

package/dist/store/global-config.js

@@ -0,0 +1,122 @@
+// src/store/global-config.ts
+/** How often instances re-read Global Config. */
+const GLOBAL_CONFIG_TTL_MS = 1e4;
+/** Max wait for the first read on a cold start; then the build bundle serves. */
+const COLD_READ_CAP_MS = 20;
+const globalConfigItemKey = (site) => `evolve_bundle_${site}`;
+/**
+* Global Config settings when the app opted in: `store: "global-config"`, or
+* `"auto"` with `EVOLVE_GLOBAL_CONFIG` (connection string) set.
+*/
+function globalConfigSettings(store, env) {
+	if (store === "memory") return null;
+	const connectionString = env.EVOLVE_GLOBAL_CONFIG;
+	if (!connectionString) {
+		if (store === "global-config") console.error("[evolve] store: \"global-config\" needs EVOLVE_GLOBAL_CONFIG; using memory");
+		return null;
+	}
+	return {
+		connectionString,
+		id: env.EVOLVE_GLOBAL_CONFIG_ID,
+		apiToken: env.EVOLVE_VERCEL_API_TOKEN,
+		teamId: env.EVOLVE_VERCEL_TEAM_ID
+	};
+}
+function defaultReader(connectionString) {
+	let client = null;
+	return async (key) => {
+		client ??= import("@vercel/global-config").then((m) => m.createClient(connectionString));
+		return (await client).get(key);
+	};
+}
+/** `"<ver>.<iat>"` of a token, without verifying it (verification is the store's job). */
+function versionOf(token) {
+	try {
+		const p = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+		return typeof p.ver === "number" && typeof p.iat === "number" ? p : null;
+	} catch {
+		return null;
+	}
+}
+const newer = (a, b) => {
+	const x = versionOf(a);
+	const y = versionOf(b);
+	if (!x) return b;
+	if (!y) return a;
+	return x.ver > y.ver || x.ver === y.ver && x.iat >= y.iat ? a : b;
+};
+/**
+* Fetcher for the memory store: reads Global Config every call; also asks the
+* cloud when Global Config is empty or every `cloudEveryMs` (so a missed
+* webhook or a stale item can't freeze the app), and returns the newer token.
+*/
+function createGlobalConfigFetcher(opts) {
+	const now = opts.now ?? Date.now;
+	const key = globalConfigItemKey(opts.site);
+	let lastCloud = -Infinity;
+	return async (etag) => {
+		let fromConfig = null;
+		try {
+			const v = await opts.read(key);
+			fromConfig = typeof v === "string" && v ? v : null;
+		} catch (e) {
+			if (!opts.cloud) return {
+				status: "error",
+				code: "network",
+				message: String(e)
+			};
+		}
+		let fromCloud = null;
+		if (opts.cloud && (!fromConfig || now() - lastCloud >= opts.cloudEveryMs)) {
+			lastCloud = now();
+			const r = await opts.cloud(fromConfig ? null : etag);
+			if (r.status === "ok") fromCloud = r.token;
+			else if (!fromConfig) return r;
+		}
+		const best = fromConfig && fromCloud ? newer(fromConfig, fromCloud) : fromConfig ?? fromCloud;
+		if (!best) return { status: "not_modified" };
+		const v = versionOf(best);
+		if (v && etag === `"${v.ver}.${v.iat}"`) return { status: "not_modified" };
+		return {
+			status: "ok",
+			token: best,
+			etag: null
+		};
+	};
+}
+/**
+* Writes the token to the site's item via the Vercel REST API (sync route).
+* Never throws; returns whether the write succeeded.
+*/
+async function writeGlobalConfig(settings, site, token, f = fetch) {
+	if (!settings.id || !settings.apiToken) {
+		console.error("[evolve] Global Config is read-only here: set EVOLVE_GLOBAL_CONFIG_ID and EVOLVE_VERCEL_API_TOKEN");
+		return false;
+	}
+	const url = new URL(`https://api.vercel.com/v1/edge-config/${settings.id}/items`);
+	if (settings.teamId) url.searchParams.set("teamId", settings.teamId);
+	try {
+		const res = await f(url, {
+			method: "PATCH",
+			headers: {
+				authorization: `Bearer ${settings.apiToken}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({ items: [{
+				operation: "upsert",
+				key: globalConfigItemKey(site),
+				value: token
+			}] }),
+			signal: AbortSignal.timeout(1e4)
+		});
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			console.error(`[evolve] Global Config write failed (${res.status})`, body.slice(0, 200));
+		}
+		return res.ok;
+	} catch (e) {
+		console.error("[evolve] Global Config write failed", e);
+		return false;
+	}
+}
+export { COLD_READ_CAP_MS, GLOBAL_CONFIG_TTL_MS, createGlobalConfigFetcher, defaultReader, globalConfigItemKey, globalConfigSettings, writeGlobalConfig };

package/dist/store/memory.d.ts

@@ -0,0 +1,39 @@
+import { FetchBundleResult } from "./fetch.js";
+import { BundlePayload, KeyRing } from "@next-evolve/protocol";
+export type BundleStore = {
+  /**
+   * Synchronous read for the request path: the current verified, unexpired
+   * bundle or null. May start a background refresh, handed to `waitUntil`.
+   */
+  peek(waitUntil?: (p: Promise<unknown>) => void): BundlePayload | null;
+  /** Verifies and installs a token (build bundle, disk, sync route). Returns whether it was accepted. */
+  load(token: string): boolean;
+  /**
+   * Fetches now (one in flight). Resolves once done. `force`: a fetch already
+   * in flight may predate a publish, so wait for it and fetch again.
+   */
+  refresh(opts?: {
+    force?: boolean;
+  }): Promise<void>;
+  /** The current bundle without side effects (no refresh; expiry not applied). */
+  current(): BundlePayload | null;
+  /** Raw token of the current bundle (for persistence). */
+  token(): string | null;
+};
+export type MemoryStoreOptions = {
+  site: string;
+  keys: KeyRing;
+  /** Fetches from the cloud. Omit for a static store (build bundle only). */
+  fetcher?: (etag: string | null) => Promise<FetchBundleResult>;
+  pollMs: number;
+  initialToken?: string | null;
+  now?: () => number;
+  random?: () => number;
+  /** Called with each token accepted after creation (persistence). */
+  onAccept?: (token: string) => void;
+};
+/**
+ * In-memory bundle store with stale-while-revalidate polling (spec §7.5):
+ * never blocks a request, one fetch in flight, ±10% jitter.
+ */
+export declare function createMemoryStore(opts: MemoryStoreOptions): BundleStore;

package/dist/store/memory.js

@@ -0,0 +1,72 @@
+import { logRateLimited } from "../core/log.js";
+import { verifyBundle } from "@next-evolve/protocol";
+// src/store/memory.ts
+/**
+* In-memory bundle store with stale-while-revalidate polling (spec §7.5):
+* never blocks a request, one fetch in flight, ±10% jitter.
+*/
+function createMemoryStore(opts) {
+	const now = opts.now ?? Date.now;
+	const random = opts.random ?? Math.random;
+	let current = null;
+	let currentToken = null;
+	let etag = null;
+	let nextCheck = 0;
+	let inflight = null;
+	const schedule = () => {
+		nextCheck = now() + opts.pollMs * (.9 + .2 * random());
+	};
+	let ready = false;
+	function load(token) {
+		const r = verifyBundle(token, {
+			keys: opts.keys,
+			site: opts.site,
+			current: current ? {
+				ver: current.ver,
+				exp: current.exp
+			} : null,
+			now: Math.floor(now() / 1e3)
+		});
+		if (!r.ok) {
+			if (r.reason !== "rollback") logRateLimited(`bundle:${r.reason}`, `bundle rejected: ${r.reason}`);
+			return false;
+		}
+		current = r.payload;
+		currentToken = token;
+		etag = `"${r.payload.ver}.${r.payload.iat}"`;
+		if (ready) opts.onAccept?.(token);
+		return true;
+	}
+	function refresh(o = {}) {
+		if (!opts.fetcher) return Promise.resolve();
+		if (inflight) return o.force ? inflight.then(() => refresh()) : inflight;
+		schedule();
+		inflight = opts.fetcher(etag).then((res) => {
+			if (res.status === "ok") load(res.token);
+			else if (res.status === "error") logRateLimited(`fetch:${res.code}`, `bundle fetch failed (${res.code})`, res.message);
+		}).catch((e) => logRateLimited("fetch:throw", "bundle fetch failed", e)).finally(() => {
+			inflight = null;
+		});
+		return inflight;
+	}
+	if (opts.initialToken) load(opts.initialToken);
+	ready = true;
+	return {
+		peek(waitUntil) {
+			if (current && now() >= current.exp * 1e3) {
+				current = null;
+				currentToken = null;
+			}
+			if (opts.fetcher && !inflight && now() >= nextCheck) {
+				const p = refresh();
+				waitUntil?.(p);
+			}
+			return current;
+		},
+		load,
+		refresh,
+		current: () => current,
+		token: () => currentToken
+	};
+}
+export { createMemoryStore };

package/dist/store/runtime.d.ts

@@ -0,0 +1,44 @@
+import { GlobalConfigReader } from "./global-config.js";
+import { BundleStore } from "./memory.js";
+import { KeyRing } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+export type RuntimeOptions = {
+  /** Signed bundle written at build time by `evolve pull` (cold-start fallback). */
+  buildBundle?: string | null;
+  /** Inject a store (tests). */
+  store?: BundleStore;
+  env?: Env;
+  /** Global Config reader (tests). */
+  globalConfigReader?: GlobalConfigReader;
+  /** Disk cache directory on long-running Node (default: $EVOLVE_CACHE_DIR, else os.tmpdir()). */
+  diskDir?: string;
+};
+/** True off serverless hosts: a process that lives across requests (next start, Docker). */
+export declare function isLongRunningNode(env?: Env): boolean;
+/** Default cloud URL (decision D29). Override with EVOLVE_CLOUD_URL. */
+export declare const DEFAULT_CLOUD_URL: string | undefined;
+/**
+ * The process-wide bundle store for this site, shared by the proxy and the
+ * render path when they run in the same process. Null when the app has no
+ * valid secret key (then everything serves control).
+ */
+export declare function getBundleStore(config: {
+  pollSeconds?: number;
+  store?: "auto" | "memory" | "global-config";
+}, opts?: RuntimeOptions): BundleStore | null;
+/**
+ * Global Config hosts, first request of an instance: a promise that resolves
+ * after one Global Config read or {@link COLD_READ_CAP_MS}, whichever comes
+ * first (spec §7.8). Null when there's nothing to wait for.
+ */
+export declare function coldStart(store: BundleStore): Promise<void> | null;
+/** This app's site id (from EVOLVE_SECRET_KEY) and trusted public keys. Cached; null without a valid key. */
+export declare function getSiteIdentity(opts?: {
+  env?: Env;
+}): {
+  site: string;
+  keys: KeyRing;
+} | null;
+/** Test helper: forget all stores. */
+export declare function resetBundleStores(): void;
+export {};