@teamscala/service-boot 0.23.525 → 0.23.527

package/src/pg-boss-mount.ts

@@ -10,16 +10,15 @@ import { getAllEntries } from "@teamscala/db/registry/accessors";
 import type { RegistryEntry } from "@teamscala/db/registry/types";
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { JobHandler } from "@teamscala/os/runtime-contracts/mount-context";
 import type { ScheduleOptions } from "pg-boss";
 import { PgBoss } from "pg-boss";
-import { pgBossHandlerRegistry } from "./pg-boss-handler-registry.ts";
-
-
 
 export interface PgBossMountContext {
 	databaseUrl: string;
 	serviceSlug: string;
 	packages: string[];
+	jobHandlers: ReadonlyMap<string, JobHandler>;
 }
 
 export interface MountedJob {
@@ -62,15 +61,16 @@ export function intervalToCron(intervalSeconds: number): string {
 }
 
 async function resolveHandler(
+	jobHandlers: ReadonlyMap<string, JobHandler>,
 	handlerSlug: string,
 	config: ScheduledJobConfig,
 	jobData?: unknown,
 ): Promise<unknown> {
-	const handler = pgBossHandlerRegistry.get(handlerSlug);
+	const handler = jobHandlers.get(handlerSlug);
 	if (!handler) {
 		throw new Error(
 			`pg-boss handler "${handlerSlug}" has no registered function — ` +
-				`register it via pgBossHandlerRegistry.register(slug, fn) before the job fires`,
+				`register it with ctx.registerJobHandler(slug, fn) in its package mount`,
 		);
 	}
 	return await handler({ config, jobData });
@@ -146,7 +146,7 @@ export async function mountPgBoss(
 			await boss.work(queueName, async (jobs) => {
 				let result: unknown;
 				for (const job of jobs) {
-					result = await resolveHandler(config.handler_slug, config, job.data);
+					result = await resolveHandler(ctx.jobHandlers, config.handler_slug, config, job.data);
 				}
 				return jobs.length === 1 ? result : undefined;
 			});

package/src/register-registry-page-route/live-loader-config.ts

@@ -19,19 +19,3 @@ export async function readLiveLoaderConfig(
 		ResourceLoaderConfigSchema,
 	);
 }
-
-/** djb2 over the config's stable JSON — short, deterministic, SSR-safe. */
-export function fingerprintLoaderConfig(config: unknown): string {
-	const json = JSON.stringify(config, sortedTopLevelKeys(config));
-	let hash = 5381;
-	for (let i = 0; i < json.length; i++) {
-		hash = ((hash << 5) + hash + json.charCodeAt(i)) | 0;
-	}
-	return (hash >>> 0).toString(36);
-}
-
-function sortedTopLevelKeys(config: unknown): string[] {
-	return config != null && typeof config === "object"
-		? Object.keys(config).sort()
-		: [];
-}

package/src/register-registry-page-route/resolve-request-graph.ts

@@ -5,90 +5,32 @@
 
 import type { PageRouteConfig } from "../register-registry-page-route.ts";
 import * as v from "valibot";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { ResourceLoaderConfigSchema } from "@teamscala/db-validation/registry-schemas/resource-loader";
 import { resolveFromLoaderConfig } from "../page-server-loader-graph.ts";
 import { decideContentPageFloor } from "../content-page-floor.ts";
 import { PrimaryResourceMissingError } from "../resource-not-found.ts";
-import {
-	staticShellGraphCache,
-	paramRouteGraphCache,
-	readCachedGraph,
-} from "./graph-cache.ts";
 
 export interface ResolveRequestGraphArgs {
 	pattern: string;
-	routeSlug: string;
 	routeConfig: PageRouteConfig;
 	loaderConfig: v.InferOutput<typeof ResourceLoaderConfigSchema>;
 	params: Record<string, string>;
-	isStaticShell: boolean;
-	serviceSlug: string;
-	/** Stable fingerprint of the LIVE loader config (fingerprintLoaderConfig).
-	 *  Appended to the graphKey so a registry row edit invalidates cached
-	 *  graphs for the route on the very next request — the graph is a
-	 *  function of the config, so the config belongs in the cache key. */
-	configFingerprint?: string;
-}
-
-/**
- * Clone a loader graph for the cache, degrading loudly rather than silently.
- *
- * ONE CLONE, TWO CALLERS. The cold path and the background-refresh path both
- * store a graph and both must survive a non-cloneable value in it — a function,
- * a Proxy, a live client handle. They previously had SEPARATE implementations:
- * the cold path carried this fallback ladder, the refresh path called
- * structuredClone bare. So a graph that the cold path stored happily threw on
- * every subsequent refresh, the cache never updated, and the entry aged out into
- * a full in-request resolve. Two copies of one decision, and the copy nobody
- * hardened is the one that fired.
- *
- * Returns undefined when the graph cannot be cloned at all; the caller then
- * declines to cache that key. Both fallbacks log, so the offending source stays
- * observable and fixable — never a silent fail-open
- * (`protective-layers-fail-explicitly`).
- */
-function cloneForCache(
-	graph: unknown,
-	graphKey: string,
-	serviceSlug: string,
-): unknown | undefined {
-	const log = getAppLogger();
-	try {
-		return structuredClone(graph);
-	} catch (err) {
-		log.warn(
-			`[scala-install:${serviceSlug}] graph-cache structuredClone failed for ${graphKey} — falling back to JSON-clone (non-cloneable value in loader graph): ${err instanceof Error ? err.message : err}`,
-		);
-		try {
-			return JSON.parse(JSON.stringify(graph)) as unknown;
-		} catch (err2) {
-			log.warn(
-				`[scala-install:${serviceSlug}] graph-cache JSON-clone also failed for ${graphKey} — cache disabled for this key (observable): ${err2 instanceof Error ? err2.message : err2}`,
-			);
-			return undefined;
-		}
-	}
 }
 
 export async function resolveRequestGraph(
 	args: ResolveRequestGraphArgs,
 ): Promise<Record<string, unknown>> {
-	const { pattern, routeSlug, routeConfig, loaderConfig, params, isStaticShell, serviceSlug, configFingerprint } = args;
+	const { pattern, routeConfig, loaderConfig, params } = args;
 
 	if (pattern === "/" && routeConfig.resource_type) {
 		throw new PrimaryResourceMissingError(routeConfig.resource_type, 200);
 	}
-	const graphKey = `graph:${routeSlug}:${params.host}:${params.path}${configFingerprint ? `:${configFingerprint}` : ""}`;
 	const primaryType = routeConfig.resource_type;
 	const hasPrimarySource =
 		!!primaryType &&
 		!!(loaderConfig as { sources?: { key: string }[] }).sources?.some(
 			(s) => s.key === primaryType,
 		);
-	const graphCache = isStaticShell
-		? staticShellGraphCache
-		: paramRouteGraphCache;
 	const typedLoaderConfig = loaderConfig as v.InferOutput<
 		typeof ResourceLoaderConfigSchema
 	> & {
@@ -96,45 +38,7 @@ export async function resolveRequestGraph(
 			v.InferOutput<typeof ResourceLoaderConfigSchema>["sources"]
 		>;
 	};
-	let resolved: Record<string, unknown>;
-	const cachedGraph = readCachedGraph(
-		graphCache,
-		graphKey,
-		() =>
-			resolveFromLoaderConfig(typedLoaderConfig, params).then(
-				(freshGraph) => {
-					const freshPrimaryMissing =
-						hasPrimarySource &&
-						primaryType &&
-						freshGraph[primaryType] == null;
-					if (freshPrimaryMissing) {
-						throw new Error(
-							`primary resource "${primaryType}" missing — skip cache update for ${graphKey}`,
-						);
-					}
-					const refreshed = cloneForCache(freshGraph, graphKey, serviceSlug);
-					if (refreshed === undefined) {
-						throw new Error(
-							`graph for ${graphKey} is not cloneable — skip cache update`,
-						);
-					}
-					return refreshed;
-				},
-			),
-	);
-	if (cachedGraph !== undefined) {
-		resolved = structuredClone(cachedGraph) as Record<string, unknown>;
-	} else {
-		resolved = await resolveFromLoaderConfig(typedLoaderConfig, params);
-		const primaryMissing =
-			hasPrimarySource && primaryType && resolved[primaryType] == null;
-		if (!primaryMissing) {
-			const cloned = cloneForCache(resolved, graphKey, serviceSlug);
-			if (cloned !== undefined) {
-				graphCache.set(graphKey, cloned);
-			}
-		}
-	}
+	const resolved = await resolveFromLoaderConfig(typedLoaderConfig, params);
 	if (hasPrimarySource && primaryType && resolved[primaryType] == null) {
 		throw new PrimaryResourceMissingError(primaryType);
 	}

package/src/register-registry-page-route/warn-uncovered-blocks.ts

@@ -4,28 +4,11 @@
  */
 
 import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { collectBlockTypes, type PuckData } from "@teamscala/puck-tree/collect-blocks";
 import type { RendererComponentEntry } from "../types.ts";
 
 const uncoveredBlocksLogged = new Set<string>();
 
-function collectBlockTypes(node: unknown, out: Set<string>): void {
-	if (Array.isArray(node)) {
-		for (const child of node) collectBlockTypes(child, out);
-		return;
-	}
-	if (node && typeof node === "object") {
-		const obj = node as Record<string, unknown>;
-		if (
-			typeof obj.type === "string" &&
-			obj.props &&
-			typeof obj.props === "object"
-		) {
-			out.add(obj.type);
-		}
-		for (const value of Object.values(obj)) collectBlockTypes(value, out);
-	}
-}
-
 export function warnUncoveredBlocks(
 	pageData: unknown,
 	components: Record<string, RendererComponentEntry>,
@@ -33,8 +16,8 @@ export function warnUncoveredBlocks(
 	path: unknown,
 	log: ReturnType<typeof getAppLogger>,
 ): void {
-	const used = new Set<string>();
-	collectBlockTypes(pageData, used);
+	const pd = pageData as { puckData?: PuckData; regions?: Array<{ puckData?: PuckData }> };
+	const used = collectBlockTypes([pd.puckData, ...(pd.regions ?? []).map((r) => r.puckData)]);
 	for (const type of used) {
 		if (type in components) continue;
 		const key = `${serviceSlug}:${type}`;

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

@@ -43,7 +43,6 @@ import {
 } from "./register-registry-page-route/proposal-brand-stamping.ts";
 import type { CreatePageHandler, RendererComponentEntry } from "./types.ts";
 import {
-	fingerprintLoaderConfig,
 	readLiveLoaderConfig,
 	type LoaderConfig,
 } from "./register-registry-page-route/live-loader-config.ts";
@@ -145,11 +144,6 @@ export async function registerRegistryPageRoute(
 			throw err;
 		}
 
-		const isStaticShell =
-			!routeConfig.resource_type &&
-			!pattern.includes(":") &&
-			!pattern.includes("*");
-
 		const loadData = async (request: Request) => {
 			const liveLoaderConfig = await readLiveLoaderConfig(loaderSlug);
 			const url = new URL(request.url);
@@ -158,13 +152,9 @@ export async function registerRegistryPageRoute(
 			params.path = url.pathname || "/";
 			const resolved = await resolveRequestGraph({
 				pattern,
-				routeSlug: routeRow.slug,
 				routeConfig,
 				loaderConfig: liveLoaderConfig as never,
 				params,
-				isStaticShell,
-				serviceSlug,
-				configFingerprint: fingerprintLoaderConfig(liveLoaderConfig),
 			});
 			const { sessionUserId, sessionOrgId } = await stampSessionContext(
 				resolved,

package/src/two-phase-full-app.ts

@@ -46,6 +46,7 @@ export async function buildFullApp(
 			databaseUrl: minimalResult.databaseUrl,
 			serviceSlug,
 			packages: config.server_packages ?? [],
+			jobHandlers: mountRegistry.jobHandlers,
 		}));
 		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: mountPgBoss DONE (${pgBossJobs.length} jobs)`);
 	} catch (error) {

package/src/pg-boss-handler-registry.ts

@@ -1,15 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- */
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import { createRegistry } from "@teamscala/generic-registry/create-registry";
-
-export type PgBossJobHandler = (ctx: {
-	config: ScheduledJobConfig;
-	jobData?: unknown;
-}) => Promise<unknown> | unknown;
-
-export const pgBossHandlerRegistry = createRegistry<PgBossJobHandler>(
-	"pg-boss-handlers",
-);

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

@@ -1,81 +0,0 @@
-// @system codegen
-// @status generated
-// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
-//
-// This suite's assertions are OWNED by the codegen band: the band module
-// carries them verbatim, this file is the emission, and hand edits here are
-// overwritten on the next run. The rationale each assertion carries moved
-// with it into the band.
-
-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

@@ -1,54 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- */
-
-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 },
-);
-
-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;
-}