@teamscala/service-boot 0.23.284

package/src/register-api-routes.ts

@@ -0,0 +1,127 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Walks `service_install.api_routes[]` and binds each entry to its
+ * registered handler (via mountRegistry.handlers, populated by server_packages
+ * during their mount phase). Unresolved handler_slug values are fatal — the
+ * service cannot boot with declared routes pointing at nothing.
+ *
+ * Injects x-remote-port header from Bun's getConnInfo so downstream
+ * handlers (MCP route) can resolve caller identity via process-tree
+ * walking when explicit caller headers are absent.
+ */
+
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+import type { Context, Hono } from "hono";
+import { getConnInfo } from "hono/bun";
+
+const REMOTE_PORT_HEADER = "x-caller-remote-port";
+// Verified socket-peer address (unforgeable transport origin). Sanitized
+// (client-supplied value deleted) then set from getConnInfo so handlers that
+// receive only a Request (e.g. mcp-tool-runtime/mount.ts) can gate on the
+// genuine transport origin per no-client-controlled-trust-signals — an external
+// attacker cannot make their TCP connection appear on the server's loopback.
+const REMOTE_ADDR_HEADER = "x-caller-remote-address";
+
+export function registerApiRoutes(
+	app: Hono,
+	config: ServiceInstallConfig,
+	mountRegistry: MountRegistry,
+	serviceSlug: string,
+): number {
+	const log = getAppLogger();
+	let count = 0;
+	for (const route of config.api_routes ?? []) {
+		const handler = mountRegistry.handlers.get(route.handler_slug);
+		if (!handler) {
+			throw new BootFatalError(
+				"register-api-routes",
+				serviceSlug,
+				`api_route "${route.method} ${route.path}" references handler_slug "${route.handler_slug}" but no server_package registered it`,
+			);
+		}
+		const method = route.method.toLowerCase() as
+			| "get"
+			| "post"
+			| "put"
+			| "delete"
+			| "patch";
+		(app as never as Record<string, (path: string, h: never) => void>)[method](
+			route.path,
+			(async (c: Context) => {
+				let req: Request = c.req.raw;
+				try {
+					if (typeof c.env !== "object" || c.env === null) {
+						log.debug(
+							`[register-api-routes] getConnInfo skipped: c.env is ${typeof c.env}`,
+						);
+					} else {
+						const info = getConnInfo(c);
+						const port = info?.remote?.port;
+						const address = info?.remote?.address ?? null;
+						// Port: set when not already present (caller-identity pane
+						// resolution preserves a chained value). Address: sanitize +
+						// re-set ONLY when getConnInfo returned one — the canonical
+						// address injection lives in service-runtime's serve.ts
+						// (server.requestIP, which reliably returns address; Hono's
+						// getConnInfo does not on Bun). Touching the address here
+						// only when we can re-verify avoids clobbering serve.ts's
+						// injection.
+						const needsPort =
+							typeof port === "number" &&
+							port > 0 &&
+							!req.headers.has(REMOTE_PORT_HEADER);
+						if (address !== null || needsPort) {
+							const headers = new Headers(req.headers);
+							if (address) {
+								headers.delete(REMOTE_ADDR_HEADER);
+								headers.set(REMOTE_ADDR_HEADER, String(address));
+							}
+							if (needsPort) headers.set(REMOTE_PORT_HEADER, String(port));
+							req = new Request(req.url, {
+								method: req.method,
+								headers,
+								body: req.body,
+							});
+						}
+						log.debug(
+							`[register-api-routes] getConnInfo port=${port ?? "undefined"} address=${address ?? "undefined"}`,
+						);
+					}
+				} catch (e) {
+					getAppLogger().error(
+						`[register-api-routes] getConnInfo failed: ${e}`,
+					);
+				}
+				const params = c.req.param();
+				return handler(req, params);
+			}) as never,
+		);
+		count++;
+	}
+
+	// CORS preflight: any service serving cross-origin browser clients (the central
+	// chat engine on mcp-ai-chat-system) needs an OPTIONS response. The shared
+	// session cookie (Domain=.scala.business) authenticates — only credentialed
+	// CORS is needed (no token-passing). Harmless for same-origin services.
+	app.options("*", (c) => {
+		const origin = c.req.header("origin");
+		if (!origin) return new Response(null, { status: 204 });
+		return new Response(null, {
+			status: 204,
+			headers: {
+				"Access-Control-Allow-Origin": origin,
+				"Access-Control-Allow-Credentials": "true",
+				"Access-Control-Allow-Methods": "POST, OPTIONS",
+				"Access-Control-Allow-Headers": "Content-Type",
+			},
+		});
+	});
+
+	return count;
+}

package/src/register-crash-handlers.ts

@@ -0,0 +1,39 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Registers process-level crash handlers (unhandledRejection, uncaughtException)
+ * for a given service. Each handler logs the error with the service slug for
+ * identification. Per constitution crash-isolation.
+ */
+
+export function registerCrashHandlers(opts: { serviceSlug: string }): {
+	unhandledRejection: boolean;
+	uncaughtException: boolean;
+} {
+	let unhandledRejection = false;
+	let uncaughtException = false;
+
+	if (process.listenerCount("unhandledRejection") === 0) {
+		process.on("unhandledRejection", (reason) => {
+			console.error(
+				`[scala-install:${opts.serviceSlug}] unhandledRejection:`,
+				reason,
+			);
+		});
+		unhandledRejection = true;
+	}
+
+	if (process.listenerCount("uncaughtException") === 0) {
+		process.on("uncaughtException", (err) => {
+			console.error(
+				`[scala-install:${opts.serviceSlug}] uncaughtException:`,
+				err,
+			);
+		});
+		uncaughtException = true;
+	}
+
+	return { unhandledRejection, uncaughtException };
+}

package/src/register-page-routes.ts

@@ -0,0 +1,62 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit directly
+ *
+ * Page route registration — reads `page_route` registry rows for the
+ * current service and delegates to `registerRegistryPageRoute`.
+ *
+ * All routes are registry-driven (Phase 1): each `page_route` row pairs
+ * a URL pattern with a `resource_loader` graph that resolves data in
+ * wave-parallel via `resolveFromLoaderConfig`. No deploy-time shell
+ * variant routes — the old `service_install.page_routes[]` Phase 2 path
+ * was removed when every active service migrated to registry-driven
+ * `page_route` rows (all 9 services carry empty arrays).
+ */
+
+import type { Hono } from "hono";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+import type { RenderModeLiteral } from "./page-route-shell-types.ts";
+import { registerPageServerClient } from "./register-page-server-client.ts";
+import { registerRegistryPageRoute } from "./register-registry-page-route.ts";
+import type { RendererComponentEntry } from "./types.ts";
+import type { CreatePageHandler } from "./types.ts";
+
+export interface RegisterPageRoutesArgs {
+	app: Hono;
+	config: ServiceInstallConfig;
+	components: Record<string, RendererComponentEntry>;
+	serviceSlug: string;
+	createPageHandler: CreatePageHandler;
+}
+
+export async function registerPageRoutes(
+	args: RegisterPageRoutesArgs,
+): Promise<string[]> {
+	const { app, config, components, serviceSlug, createPageHandler } = args;
+
+	await registerPageServerClient(serviceSlug);
+
+	const declaredMode = (config as { render_mode?: string }).render_mode;
+	const renderMode: RenderModeLiteral =
+		declaredMode === "portal"
+			? "portals"
+			: declaredMode === "utility"
+				? "utility"
+				: "public";
+	const authMode = (config as { auth?: string }).auth ?? "none";
+	const providers = ((config as { providers?: string[] }).providers ??
+		[]) as string[];
+
+	const registryPatterns = await registerRegistryPageRoute({
+		app,
+		serviceSlug,
+		components,
+		createPageHandler,
+		authMode,
+		renderMode,
+		providers,
+	});
+
+	return registryPatterns;
+}

package/src/register-page-server-client.ts

@@ -0,0 +1,109 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Registers the system server-client for page-server SSR rendering. Composes
+ * the platform-owned routers into the service's generated `appRouter` and
+ * stashes the resulting client via setServerClient. Called once at boot before
+ * any page route handler fires.
+ */
+
+import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+export async function registerPageServerClient(
+	serviceSlug: string,
+): Promise<void> {
+	const log = getAppLogger();
+	try {
+		const mod = (await import(
+			"@teamscala/service-boot/page-server-orpc/server-client" as string
+		)) as {
+			setServerClient: (client: unknown) => void;
+		};
+		const { createRouterClient } = await import("@orpc/server");
+		const { getPrisma } = await import("@teamscala/db/prisma-registry");
+		// Load the composed CRUD router via getAppRouter() — the SAME registered
+		// instance the /api/rpc mount uses (mount-orpc-router.ts). The previous code
+		// did a raw second `import(cwd + "prisma/generated/orpc/routers/index.ts")`,
+		// re-loading the generated routers under a different module specifier than
+		// the mount already used; in the full boot process that re-execution throws,
+		// and the throw was swallowed by a SILENT catch — leaving the page-server
+		// client without the CRUD models, so every data-backed page 500s
+		// ("client.<model> is undefined", the scala-sign prod outage). existsSync
+		// gates the legitimate no-router case (daemon/portal services that own no DB
+		// schema) so it stays a clean skip, never a misleading warn.
+		const { existsSync } = await import("node:fs");
+		const routerPath = join(
+			process.cwd(),
+			"prisma/generated/orpc/routers/index.ts",
+		);
+		let appRouter: Record<string, unknown> | null = null;
+		if (existsSync(routerPath)) {
+			try {
+				const { getAppRouter } = await import("@teamscala/orpc/app-router");
+				appRouter = ((await getAppRouter()) as Record<string, unknown>) ?? null;
+			} catch (err) {
+				// A genuine load failure here means every data-backed page 500s, so it
+				// must surface, never be swallowed (protective-layers-fail-explicitly).
+				log.warn(
+					`[scala-install:${serviceSlug}] appRouter load failed — data-backed pages will 500: ${err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err)}`,
+				);
+			}
+		}
+		const { puckPagesRouter } = await import(
+			"@teamscala/service-boot/page-server-orpc/puck-pages-router"
+		);
+		const { portalDiagRouter } = await import(
+			"@teamscala/service-boot/page-server-orpc/portal-diagnostics-router"
+		);
+		const { userPreferencesRouter } = await import(
+			"@teamscala/service-boot/page-server-orpc/user-preferences-router"
+		);
+		const { auditRevertRouter } = await import(
+			"@teamscala/service-boot/page-server-orpc/audit-revert-router"
+		);
+		const composed = {
+			...((appRouter as Record<string, unknown> | null) ?? {}),
+			puckPages: puckPagesRouter,
+			portalDiag: portalDiagRouter,
+			userPreferences: userPreferencesRouter,
+			auditRevert: auditRevertRouter,
+		};
+		const { loadRegistryConfig } = await import(
+			"@teamscala/db/registry/load-config"
+		);
+		const { PlatformIdentitySchema } = await import(
+			"@teamscala/db-validation/registry-schemas/platform-identity"
+		);
+		// Platform org id is a registry value (registries-are-source-of-truth),
+		// not a hardcoded literal — read from config/platform-identity.
+		const platformIdentity = await loadRegistryConfig(
+			"config",
+			"platform-identity",
+			PlatformIdentitySchema,
+		);
+		const client = createRouterClient(
+			composed as never,
+			{
+				context: {
+					prisma: getPrisma(),
+					user: {
+						id: "system",
+						isSuperAdmin: true,
+						organisationId: platformIdentity.platformOrganisationId,
+					},
+				},
+			} as never,
+		);
+		mod.setServerClient(client);
+		log.info(
+			`[scala-install:${serviceSlug}] ORPC serverClient registered (system:super-admin)`,
+		);
+	} catch (err) {
+		log.warn(
+			`[scala-install:${serviceSlug}] Failed to load appRouter for serverClient: ${err instanceof Error ? err.message : err}`,
+		);
+	}
+}

package/src/register-registry-page-route/ai-chat-prefetch.ts

@@ -0,0 +1,106 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * SSR-prefetch the signed-in user's AI-chat conversation so a click-opened AI
+ * panel renders the real conversation on first paint. Extracted from
+ * register-registry-page-route.ts (single-purpose-file split).
+ */
+import { getServerClient } from "../page-server-orpc/server-client.ts";
+
+/**
+ * Deep-find the serving `website_id` in the loader graph (resolved). The
+ * Utility/Portal shell carries the website id (not a slug) under a loader
+ * source key; the client RegionPageSwap reads it from loaderData.*.website_id
+ * the same way. Bounded walk (cycle-safe) over the resolved loader results.
+ */
+function findWebsiteId(root: unknown): string | undefined {
+	if (!root || typeof root !== "object") return undefined;
+	const seen = new Set<unknown>();
+	const stack: unknown[] = [root];
+	while (stack.length > 0) {
+		const node = stack.pop() as Record<string, unknown> | null;
+		if (!node || typeof node !== "object" || seen.has(node)) continue;
+		seen.add(node);
+		for (const key in node) {
+			if (key === "website_id" && typeof node[key] === "string")
+				return node[key] as string;
+			const val = node[key];
+			if (val && typeof val === "object") stack.push(val);
+		}
+	}
+	return undefined;
+}
+
+/**
+ * SSR-prefetch the signed-in user's AI-chat conversation so a CLICK-opened AI
+ * panel renders the real conversation on first paint — never a loading gate
+ * (ssr-then-live-handoff). The AiChat block lives on the /ai PANEL page, which
+ * isn't rendered when the panel is closed, so its block serverLoader can't run
+ * at page-load; this prefetches server-side (regardless of panel open-state) +
+ * stamps pageData.aiChatSession, which AiChat reads on mount. The agent is
+ * resolved from the /ai panel page's own AiChat block (single source of truth —
+ * no duplicate config to drift). Fired in parallel with the post-processors +
+ * bounded by their window; a failure degrades silently to the client-side
+ * createOrRestore fallback, never an error page.
+ */
+export async function prefetchAiChatSession(
+	resolved: Record<string, unknown>,
+	sessionUserId: string | undefined,
+	orgId: string | undefined,
+): Promise<Record<string, unknown> | null> {
+	if (!sessionUserId || !orgId) return null;
+	// The serving website id is nested in the loader graph (the client
+	// RegionPageSwap reads it from loaderData.*.website_id the same way) — the
+	// Utility/Portal shell carries the website id, not a slug. Deep-find it.
+	const websiteSlug = findWebsiteId(resolved);
+	if (!websiteSlug) return null;
+	try {
+		const client = getServerClient() as {
+			regions?: {
+				loadPage?: (i: {
+					websiteSlug: string;
+					path: string;
+				}) => Promise<{
+					puckData?: {
+						content?: Array<{
+							type?: string;
+							props?: { agent?: string; agentId?: string };
+						}>;
+					};
+				} | null>;
+			};
+			fn?: {
+				chatSession?: {
+					createOrRestore?: (i: {
+						agentId: string;
+						organisationId: string;
+						userId?: string;
+					}) => Promise<{
+						conversationId: string;
+						messages?: unknown[];
+						tokenTotals?: unknown;
+						hasMore?: boolean;
+					}>;
+				};
+			};
+		};
+		// Load the /ai panel page config (cached 60s SWR — static, no per-user
+		// data) + find the AiChat block's agent (the single source of truth).
+		const page = await client.regions?.loadPage?.({ websiteSlug, path: "/ai" });
+		const aiBlock = page?.puckData?.content?.find((b) => b?.type === "AiChat");
+		const agentId = aiBlock?.props?.agent ?? aiBlock?.props?.agentId;
+		if (!agentId) return null;
+		const session = await client.fn?.chatSession?.createOrRestore?.({
+			agentId,
+			organisationId: orgId,
+			userId: sessionUserId,
+		});
+		if (!session?.conversationId) return null;
+		return session as Record<string, unknown>;
+	} catch {
+		// Prefetch failed — client-side createOrRestore is the fallback.
+		return null;
+	}
+}

package/src/register-registry-page-route/graph-cache.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Regression guard for readCachedGraph's stale-while-revalidate decision
+ * (capability-harvest-on-split / what-must-have-a-test). The fold onto
+ * @teamscala/cache's getWithMeta + refreshInBackground must keep firing the
+ * background refresh past the fresh window — if it ever stops, the page-route
+ * graph cache silently degrades to fresh-or-miss (the measured 3.8s
+ * cache-expired in-request regression the SWR exists to prevent).
+ */
+import { describe, expect, test } from "bun:test";
+import { createCache } from "@teamscala/cache/create-cache";
+import { readCachedGraph } from "./graph-cache.ts";
+
+const delay = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+describe("readCachedGraph", () => {
+	test("fresh hit returns the cached value and fires NO refresh", async () => {
+		const cache = createCache<unknown>("graph-cache-test:fresh", {
+			maxSize: 4,
+			ttlMs: 1000,
+			staleTtlMs: 1000,
+		});
+		let refreshCalls = 0;
+		cache.set("k", "v");
+		expect(readCachedGraph(cache, "k", async () => ++refreshCalls)).toBe("v");
+		await delay(5);
+		expect(refreshCalls).toBe(0);
+	});
+
+	test("stale hit returns the cached value AND fires the background refresh", async () => {
+		const cache = createCache<unknown>("graph-cache-test:stale", {
+			maxSize: 4,
+			ttlMs: 20,
+			staleTtlMs: 5000,
+		});
+		let refreshCalls = 0;
+		cache.set("k", "v");
+		await delay(40); // past ttlMs (fresh) → within staleTtlMs → stale
+		// Serves the stale value instantly...
+		expect(readCachedGraph(cache, "k", async () => ++refreshCalls)).toBe("v");
+		// ...and fires exactly one background refresh.
+		await delay(5);
+		expect(refreshCalls).toBe(1); // FAILS if the background refresh stops firing
+	});
+
+	test("miss returns undefined so the caller resolves synchronously", () => {
+		const cache = createCache<unknown>("graph-cache-test:miss", {
+			maxSize: 4,
+			ttlMs: 1000,
+			staleTtlMs: 1000,
+		});
+		let refreshCalls = 0;
+		expect(
+			readCachedGraph(cache, "absent", async () => ++refreshCalls),
+		).toBeUndefined();
+		expect(refreshCalls).toBe(0);
+	});
+
+	test("stale refresh is single-flight (a second stale read while in-flight does not re-fire)", async () => {
+		const cache = createCache<unknown>("graph-cache-test:dedup", {
+			maxSize: 4,
+			ttlMs: 20,
+			staleTtlMs: 5000,
+		});
+		let refreshCalls = 0;
+		let resolveRefresh: (value: number) => void = () => {};
+		const slowRefresh = (): Promise<number> =>
+			new Promise<number>((resolve) => {
+				refreshCalls++;
+				resolveRefresh = resolve;
+			});
+		cache.set("k", "v");
+		await delay(40); // stale
+		readCachedGraph(cache, "k", slowRefresh); // fires refresh → in-flight
+		readCachedGraph(cache, "k", slowRefresh); // deduped against the same in-flight map
+		await delay(5);
+		expect(refreshCalls).toBe(1); // only ONE refresh in flight, not two
+		resolveRefresh(refreshCalls);
+		await delay(5);
+	});
+});

package/src/register-registry-page-route/graph-cache.ts

@@ -0,0 +1,90 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten @indivisible-unit
+ * @edit edit directly
+ *
+ * The two SWR loader-graph caches (static-shell + parameterised routes) for the
+ * registry page registrar, plus readCachedGraph — the testable stale-while-
+ * revalidate read. Extracted from register-registry-page-route.ts so the SWR
+ * decision is unit-testable independent of the Hono/DB/graph machinery.
+ *
+ * The SWR contract rides @teamscala/cache directly (the hand-rolled `at` timestamp,
+ * FRESH_MS window, and graphRefreshInflight single-flight Set are gone): each
+ * cache is configured ttlMs = the fresh window (serve, no refresh) + staleTtlMs =
+ * the rest (serve stale + fire ONE background refresh). readCachedGraph uses
+ * getWithMeta for the fresh/stale/miss decision and cache.refreshInBackground
+ * for the fire-and-forget refresh — deduped against the cache's own in-flight map
+ * (so delete/clear/disable drop its flights, and a refresh in flight across an
+ * invalidation can no longer resurrect the dropped entry).
+ *
+ * Graphs deep-clone on BOTH set and get at the caller (registerRegistryPageRoute):
+ * gateAgreementContent + downstream block resolution MUTATE the object in place,
+ * so handing a cached tree out twice would ship request A's resolved data to
+ * request B (ssr-first-tick-parity). Clone-on-get stays local to the caller.
+ */
+import { createCache } from "@teamscala/cache/create-cache";
+
+// The structural surface readCachedGraph touches (getWithMeta + refreshInBackground).
+// ManagedCache<unknown> satisfies it; declared locally so the SWR decision does
+// not depend on the cache package's internal type export path.
+type GraphCache = {
+	getWithMeta(key: string): { value: unknown; stale: boolean } | undefined;
+	refreshInBackground(
+		key: string,
+		compute: () => Promise<unknown>,
+		opts?: { ttlMs?: number },
+	): void;
+};
+
+// Static-shell routes (no resource_type, no :params, no wildcard — the fleet
+// dashboard's "/", any fixed page) resolve the SAME loader graph every request:
+// pure page/website structure that changes only on editor writes, yet every SSR
+// re-paid the full graph over the tunnel DB (load=1.8-2.2s measured 2026-06-06 —
+// the whole remaining load tier). 60s fresh (ttlMs) + 540s stale (staleTtlMs) =
+// 600s total; past the fresh window a hit still serves instantly and fires ONE
+// background re-resolve. Without SWR every cache-expiry request paid the full
+// resolve in-request — measured 3.8s on a cache-expired hit.
+export const staticShellGraphCache = createCache<unknown>(
+	"registry-route:static-shell-graph",
+	{ maxSize: 64, ttlMs: 60_000, staleTtlMs: 540_000 },
+);
+
+// Parameterised routes (:param / wildcard — record pages, the portal catchall)
+// were permanently uncacheable: every hit re-paid the full graph resolve (~2.3s
+// from the dev host). The graphKey encodes routeRow.slug + host + path and the
+// graph is purely path-determined (searchParams, theme, agreement gating all
+// apply AFTER the clone), so a short fresh window is safe: a record edit is
+// visible within 15s on a trafficked page (background refresh). 15s fresh
+// (ttlMs) + 285s stale (staleTtlMs) = 300s total.
+export const paramRouteGraphCache = createCache<unknown>(
+	"registry-route:param-route-graph",
+	{ maxSize: 256, ttlMs: 15_000, staleTtlMs: 285_000 },
+);
+
+/**
+ * Stale-while-revalidate read of a cached loader graph.
+ *
+ * - Fresh hit (within ttlMs): return the cached graph, no refresh.
+ * - Stale hit (within ttlMs + staleTtlMs): return the cached graph AND fire ONE
+ *   background refresh via cache.refreshInBackground — single-flight (deduped
+ *   against the cache's in-flight map), never rejects, leaves the stale entry in
+ *   place on failure. The caller deep-clones the returned value before use.
+ * - Miss (past staleTtlMs, or never cached): return undefined — the caller
+ *   resolves synchronously and cache.set()s the clone.
+ *
+ * The refresh callback must return a graph safe to store. To SKIP caching a
+ * refresh result (e.g. a primary-missing / dead-link graph that must stay
+ * per-request so a just-created record appears immediately), the callback THROWS
+ * — refreshInBackground catches it, leaves the stale entry, and logs one line
+ * (an observable dead-link signal, not a hard error).
+ */
+export function readCachedGraph(
+	cache: GraphCache,
+	key: string,
+	refresh: () => Promise<unknown>,
+): unknown | undefined {
+	const meta = cache.getWithMeta(key);
+	if (meta === undefined) return undefined;
+	if (meta.stale) cache.refreshInBackground(key, refresh);
+	return meta.value;
+}