@teamscala/service-boot 0.23.284

package/src/server-error-page.ts

@@ -0,0 +1,95 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The branded HTML error page for a FAILED PAGE RENDER — the page-server
+ * render catch's response surface (constitution `error-responses-via-error-
+ * report`). When SSR resolve+render fails (render budget exhausted, DEGRADED
+ * protective layer, a thrown loader), the browser is mid-navigation: serving
+ * a JSON body there is the violation this closes (2026-07-24: the operator
+ * saw a raw `{"error":"Request failed"}` blob where the dashboard should be).
+ *
+ * Classification stays in `buildErrorReport` (`@teamscala/os`) — the ONE
+ * classifier; this file is ONLY the HTML shaper for the page-navigation
+ * surface (API/ORPC `onError` keeps the JSON body, consumed by code). It
+ * renders the report's already-decided status + Retry-After + message, so the
+ * screen, the log line, and the GlitchTip event all share one `errorId`.
+ *
+ * Deliberately NOT a Puck page: it must render even when data loading is what
+ * failed. Sibling of `resource-not-found.ts` (the missing-resource floor) —
+ * same dark branded template + org-logo resolver, distinct trigger.
+ */
+
+import { escapeHtml } from "@teamscala/formatters/escapeHtml";
+import { brandLogoImgTag } from "@teamscala/os/brand/brand-logo-img-tag";
+import type { ErrorReport } from "@teamscala/os/errors/error-report";
+
+/**
+ * Render an `ErrorReport` as a branded HTML page. Pure shaper — the caller
+ * classifies via `buildErrorReport` and resolves the logo first. Skew-tolerant
+ * by construction: a missing logo degrades to a plain branded dark page.
+ */
+export function buildServerErrorPageResponse(
+	report: ErrorReport,
+	logoUrl?: string | null,
+): Response {
+	const transient = report.transient === true;
+	// A transient failure (render timeout, DEGRADED budget, module swap) is
+	// recoverable — the screen says "coming back", not "broken". Everything
+	// else is a real error: show the message + errorId so the operator can
+	// find it in GlitchTip without grepping logs.
+	const title = transient ? "Temporarily unavailable" : "Something went wrong";
+	const heading = transient ? "This page is taking longer than expected" : "We couldn't load this page";
+	const explanation = transient
+		? (report.reason ?? "The service is busy or warming up. It should be available again shortly.")
+		: (report.message || "An unexpected error occurred while rendering this page.");
+	// Inline data-URI src (resolveErrorPageLogo) + reserved width/height via
+	// the shared helper — the logo ships in the initial HTML bytes, no
+	// post-paint proxy pop-in under degraded conditions
+	// (logos-inline-on-branded-server-pages).
+	const logoImg = brandLogoImgTag(logoUrl, { height: 40, width: 160 });
+	const retry = transient
+		? `<p style="margin-top:.75rem">It should reload automatically — or <a href="/" style="color:#cfcfd6">try again</a>.</p>`
+		: "";
+	const idLine = report.errorId
+		? `<p style="margin-top:1.25rem;font-size:.8rem;color:#6b7280">Reference&nbsp;<code style="color:#9aa0ab">${escapeHtml(report.errorId)}</code></p>`
+		: "";
+	const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${escapeHtml(title)}</title>
+<link rel="icon" href="/favicon.ico">
+<style>
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center;
+         justify-content: center; background: #0a0e1a; color: #e7e7e7;
+         font-family: system-ui, sans-serif; text-align: center; }
+  main { padding: 2rem; max-width: 30rem; }
+  img  { height: 48px; width: auto; margin-bottom: 1.5rem; }
+  h1   { font-size: 1.25rem; font-weight: 600; margin: 0 0 .5rem; }
+  p    { color: #9aa0ab; line-height: 1.5; margin: 0; }
+  a:hover { opacity: .9; }
+</style>
+</head>
+<body>
+<main>
+  ${logoImg}
+  <h1>${escapeHtml(heading)}</h1>
+  <p>${escapeHtml(explanation)}</p>
+  ${retry}
+  ${idLine}
+</main>
+</body>
+</html>`;
+	const headers: Record<string, string> = {
+		"content-type": "text/html; charset=utf-8",
+		"cache-control": "no-store, no-transform",
+	};
+	if (report.retryAfter !== undefined) {
+		headers["retry-after"] = String(report.retryAfter);
+	}
+	return new Response(html, { status: report.http.status, headers });
+}

package/src/start-scheduled-jobs.ts

@@ -0,0 +1,84 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Starts `service_install.scheduled_jobs[]`. Two kinds:
+ *
+ *   - `long_running`: handler invoked once at boot, runs for the lifetime of
+ *      the process (e.g. SSE subscribers, WAL watchers). Failures are logged.
+ *   - `recurring`: declared here but cron scheduling lands via pg-boss in a
+ *      follow-up — currently a no-op log.
+ *
+ * Implementations are registered by server_packages via
+ * ctx.registerScheduledJob during the mount phase.
+ */
+
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+
+export function startScheduledJobs(
+	config: ServiceInstallConfig,
+	mountRegistry: MountRegistry,
+	serviceSlug: string,
+): void {
+	const log = getAppLogger();
+	for (const rawJob of config.scheduled_jobs ?? []) {
+		const job = rawJob as {
+			name: string;
+			kind: string;
+			[key: string]: unknown;
+		};
+		const handler = mountRegistry.scheduledJobs.get(job.name);
+		if (!handler) {
+			log.warn(
+				`[scala-install:${serviceSlug}] scheduled_job "${job.name}" has no registered handler — skipping`,
+			);
+			continue;
+		}
+		if (job.kind === "long_running") {
+			handler({ name: job.name, attempt: 1 })?.catch?.((err: unknown) => {
+				log.error(
+					`[scala-install:${serviceSlug}] long_running job "${job.name}" failed: ${err}`,
+				);
+			});
+			log.info(
+				`[scala-install:${serviceSlug}] long_running job "${job.name}" started`,
+			);
+		} else {
+			// Recurring handlers manage their own setInterval — invoke once at
+			// boot so the timer arms. pg-boss-driven scheduling lands separately
+			// for cluster-wide coordination, but fire-and-forget is sufficient
+			// for single-node dev and matches how long_running handlers behave.
+			handler({ name: job.name, attempt: 1 })?.catch?.((err: unknown) => {
+				log.error(
+					`[scala-install:${serviceSlug}] recurring job "${job.name}" boot invocation failed: ${err}`,
+				);
+			});
+			log.info(
+				`[scala-install:${serviceSlug}] recurring job "${job.name}" started`,
+			);
+		}
+	}
+
+	// Hollow-shell detection — the symmetric half of the row-without-handler
+	// warn above. A handler a server_package registered at mount but the
+	// service_install row never declared is silently dead: the package believes
+	// its watchdog/subscriber runs, the runtime never invokes it, and nothing
+	// says so. A registry edit that rewrites scheduled_jobs drops an entry with
+	// no diff and no error, so boot is the only place both sets are known.
+	// Twice now a watchdog sat dead this way — the fleet stalled-run watchdog
+	// (2026-06-05) and task-list-watchdog, dropped by a row edit on 2026-07-23
+	// and unnoticed for two days. Loud at boot so the gap is visible same day.
+	const declared = new Set(
+		(config.scheduled_jobs ?? []).map((j) => (j as { name: string }).name),
+	);
+	for (const name of mountRegistry.scheduledJobs.keys()) {
+		if (!declared.has(name)) {
+			log.error(
+				`[scala-install:${serviceSlug}] scheduled job handler "${name}" is registered but NOT declared in service_install.scheduled_jobs — it will NEVER run. Add it to the row or remove the registration.`,
+			);
+		}
+	}
+}

package/src/two-phase-boot.ts

@@ -0,0 +1,449 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Two-phase boot for UI services. Splits the boot process into:
+ * 1. Minimal app (tool-only surface): ORPC, data routes, auth gates
+ * 2. Full app (with pages and hydration): adds block discovery, page routes,
+ *    client asset building, boot hooks, scheduled jobs
+ *
+ * The minimal app starts serving immediately (<10s), then the full app is
+ * built in the background and atomically swapped in. This eliminates the
+ * ~25s channel outage window during scala-agents restart.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+import { createTimer } from "@teamscala/timing/create-timer";
+import { Hono } from "hono";
+import { compress } from "hono/compress";
+import { cors } from "hono/cors";
+import { timing } from "hono/timing";
+import { attachContentGateAccess } from "./content-gate/access.ts";
+import { initGateTtls } from "./gate-ttls.ts";
+import { agreementAccessConfig } from "./agreement-gate.ts";
+import { proposalAccessConfig } from "./proposal-gate.ts";
+import { gptAccessConfig } from "./gpt-gate.ts";
+import { attachProposalAccept } from "./attach-proposal-accept.ts";
+import { attachAgreementMagic } from "./attach-agreement-magic.ts";
+import { getCookieDomain } from "@teamscala/db/registry/cookie-domain";
+import { attachProposalMagic } from "./attach-proposal-magic.ts";
+import { attachPortalMembers } from "./attach-portal-members.ts";
+import { attachTransfersUpload } from "./attach-transfers-upload.ts";
+import { attachAuthGate } from "./auth-gate.ts";
+import { attachRequestLogger } from "./install-logging.ts";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+import { mountOrpcRouter } from "./mount-orpc-router.ts";
+import { mountServerPackages, preloadServerPackages } from "./mount-server-packages.ts";
+import { mountPgBoss } from "./pg-boss-mount.ts";
+import { registerApiRoutes } from "./register-api-routes.ts";
+import { readinessGate } from "./readiness-gate.ts";
+import { registerStaticAssets } from "./register-static-assets";
+import { registerWsRoutes } from "./register-ws-routes.ts";
+import { createRequestErrorHandler } from "./hono-error-handler.ts";
+import {
+	buildResourceNotFoundResponse,
+	resolveErrorPageLogo,
+} from "./resource-not-found.ts";
+import { injectSecurityHeaders } from "./security-headers.ts";
+import { startScheduledJobs } from "./start-scheduled-jobs.ts";
+import type { PageServerDeps } from "./ui-service.ts";
+import { registerPageRoutes } from "./register-page-routes.ts";
+import { runBootHookList } from "./run-boot-hook-list.ts";
+import { buildClientAssets } from "./build-client-assets.ts";
+import { discoverBlocks } from "./discover-blocks.ts";
+import { swapApp } from "./mutable-app-ref.ts";
+import type { CreatePageHandler } from "./types.ts";
+
+// Module-level storage for the real page handler, updated when Phase 2 completes.
+// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
+let realPageHandler: CreatePageHandler | null = null;
+let fullAppReady = false;
+
+/**
+ * Set the real page handler (called when Phase 2 completes).
+ */
+export function setPageHandler(handler: CreatePageHandler): void {
+	realPageHandler = handler;
+	fullAppReady = true;
+}
+
+/**
+ * Get the current page handler state.
+ */
+export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
+	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
+}
+
+export interface MinimalAppResult {
+	app: Hono;
+	mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;
+	apiRouteCount: number;
+	wsRouteCount: number;
+	pageRouteCount: number;
+	config: ServiceInstallConfig;
+	serviceSlug: string;
+	databaseUrl: string;
+	blockPackages: string[];
+	components: Record<string, unknown>; // From discoverBlocks
+	loaded: string[]; // Discovered block names
+	skipped: string[]; // Skipped block names
+}
+
+export interface FullAppResult {
+	app: Hono;
+	blocks: { slug: string; packagePath: string }[];
+	routes: string[];
+	pgBossJobs: Array<{ handlerSlug: string }>;
+}
+
+/**
+ * Build the minimal tool-only app. This excludes the expensive operations:
+ * - Client asset building (Vite build)
+ * - Boot hooks (may have expensive initialization)
+ * - Scheduled jobs (can start later)
+ * - pg-boss (can start later)
+ *
+ * CRITICAL: All route registration MUST happen here before serving, because
+ * Hono's RegExpRouter compiles on the first request and becomes immutable.
+ * Once compiled, no new routes can be added. So we include:
+ * - Block discovery and page routes (registers all page paths)
+ * - All other routes (API, WS, data, static assets)
+ *
+ * The minimal app includes everything needed for MCP tools and ORPC:
+ * - Error handling, readiness gate, health check
+ * - Security headers, CORS, compression, timing
+ * - Content gate access, auth gates, static assets
+ * - ORPC router, API routes, WS routes, data routes, page routes
+ */
+export async function buildMinimalApp(
+	config: ServiceInstallConfig,
+	serviceSlug: string,
+	databaseUrl: string,
+): Promise<MinimalAppResult> {
+	const log = getAppLogger();
+	const blockPackages = ((config as { block_packages?: string[] })
+		.block_packages ?? []) as string[];
+
+	const app = new Hono();
+
+	// Per-step instrumentation inside the boot-ui-service phase. Same
+	// createTimer + wall-clock convention as create-boot-pipeline's runPhase
+	// (timing-is-the-only-timing, per-phase-instrumentation) — NOT a second
+	// telemetry surface. The boot-ui-service phase is 60% of boot; this
+	// breakdown localises the cost so optimisation targets the real hotspot
+	// instead of guessing. Spans flow to GlitchTip (timing's trace-emitter is
+	// wired by the time we reach here); the breakdown line is `pm2 logs`-visible.
+	const stepTimings: Record<string, number> = {};
+	async function runStep<T>(step: string, fn: () => Promise<T>): Promise<T> {
+		const timer = createTimer(`${serviceSlug}:boot.minimal.${step}`);
+		const start = Date.now();
+		try {
+			return await timer.timeAsync(fn);
+		} finally {
+			stepTimings[step] = Date.now() - start;
+		}
+	}
+
+	// Error handlers
+	app.onError(createRequestErrorHandler("service-boot:minimal"));
+
+	app.notFound(async (c) => {
+		const accept = c.req.header("accept") ?? "";
+		if (/\btext\/html\b/.test(accept)) {
+			const logo = await resolveErrorPageLogo(serviceSlug);
+			return buildResourceNotFoundResponse("page", logo, 404);
+		}
+		return c.json({ error: "Not Found" }, 404);
+	});
+
+	// Core middleware
+	app.use("*", readinessGate);
+	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.use("*", injectSecurityHeaders);
+	const cookieDomain = await getCookieDomain();
+	app.use(
+		"*",
+		cors({
+			origin: (origin) => {
+				if (!origin) return "";
+				if (origin.endsWith(cookieDomain)) return origin;
+				return "";
+			},
+			allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+			allowHeaders: ["Content-Type", "Authorization"],
+			credentials: true,
+		}),
+	);
+	app.use("*", compress());
+	app.use("*", timing());
+	attachRequestLogger(app, serviceSlug);
+
+	// Fire independent I/O + compilation NOW, overlapping with the gate chain
+	// below. These three touch NO app route and have no ordering dependency on
+	// the gate/mount sequence, so they run concurrently with it:
+	// - preloadServerPackages: warms Bun's module cache (CPU-bound compilation
+	//   that overlaps the gate chain's cross-internet DB I/O — same speculative
+	//   pattern as create-boot-pipeline's preloads). mountServerPackages later
+	//   hits the cache (instant imports), paying only the ~33ms of mount work.
+	// - initGateTtls: loads config rows into module-level vars. The TTL getters
+	//   are read at REQUEST time (inside route-handler closures), not at boot,
+	//   so this only needs to finish before serving — safe to run in parallel.
+	// - discoverBlocks: loads the page-manifest (no app mutation, no gate
+	//   dependency). Its result is consumed by registerPageRoutes much later.
+	const serverPackages = ((config as { server_packages?: string[] })
+		.server_packages ?? []) as string[];
+	const preloadPromise = runStep("preload-server-packages", () =>
+		preloadServerPackages(serverPackages),
+	);
+	const ttlPromise = runStep("init-gate-ttls", () => initGateTtls());
+	const discoverPromise = runStep("discover-blocks", () =>
+		discoverBlocks(blockPackages),
+	);
+	// Attach an immediate rejection sink: discoverPromise is fired here but
+	// awaited much later (after the gate chain + mounts). If discoverBlocks
+	// rejects during that overlap window, the rejection would surface as an
+	// unhandledRejection before the await below can catch it. The sink is a
+	// no-op — the real error still propagates at the `await discoverPromise`
+	// site because each consumer of a rejected promise receives the rejection.
+	discoverPromise.catch(() => {});
+
+	// Public access endpoints — MUST be registered before the auth gate (Hono
+	// dispatches middleware + handlers in registration order; the content-gate
+	// POST routes and magic-link endpoints are public and must be reachable
+	// without a session, so they precede the auth gate's app.use("*") wildcard).
+	// These are mutually independent — distinct paths, no shared mutable state
+	// beyond the Hono app's synchronous route array — so they parallelise.
+	await runStep("public-routes", () =>
+		Promise.all([
+			attachContentGateAccess(app, serviceSlug, agreementAccessConfig),
+			attachContentGateAccess(app, serviceSlug, proposalAccessConfig),
+			attachContentGateAccess(app, serviceSlug, gptAccessConfig),
+			attachProposalAccept(app, serviceSlug),
+			attachAgreementMagic(app, serviceSlug),
+			attachProposalMagic(app, serviceSlug),
+			attachPortalMembers(app),
+			attachTransfersUpload(app),
+		]),
+	);
+
+	// Auth gate — registers /api/auth/* + the session-check wildcard middleware.
+	// MUST follow the public routes above (load-bearing Hono registration order)
+	// and MUST precede mountServerPackages: server-package daemon routes (e.g.
+	// cli-session's /rpc/*) are subject to the session gate, which requires the
+	// gate's wildcard registered first to apply. Running these concurrently would
+	// make that ordering non-deterministic — so the gate stays serial here.
+	await runStep("attach-auth-gate", () =>
+		attachAuthGate(app, config, serviceSlug),
+	);
+	registerStaticAssets(app, serviceSlug, config.brand_org);
+
+	// Server packages — the cold imports were preloaded above and are now in
+	// Bun's module cache, so this pays only the mount work (~33ms, not ~2.8s of
+	// serial compilation). Route registration happens HERE (after the auth gate),
+	// preserving the gate-vs-daemon-route ordering.
+	const mountRegistry = await runStep("mount-server-packages", () =>
+		mountServerPackages(app, config, serviceSlug),
+	);
+	// Ensure the speculative preload finished before proceeding (it populates
+	// the same cache mountServerPackages just consumed; awaiting now is a no-op
+	// if the preload already settled, and makes the ordering guarantee explicit).
+	await preloadPromise;
+	const apiRouteCount = registerApiRoutes(app, config, mountRegistry, serviceSlug);
+
+	if (config.orpc_router !== false) {
+		await runStep("mount-orpc-router", () => mountOrpcRouter(app, serviceSlug));
+	}
+
+	const wsRouteCount = await runStep("register-ws-routes", () =>
+		registerWsRoutes(app, config, mountRegistry, serviceSlug),
+	);
+
+	// Resolve the deferred TTL load (started at the top — should be long done,
+	// overlapped with the gate chain + mount work). The getters are read at
+	// request time, but the cache must be populated before the first request.
+	await ttlPromise;
+
+	// CRITICAL: Block discovery and page routes MUST be registered BEFORE serving,
+	// because Hono's RegExpRouter compiles on first request and becomes immutable.
+	// We defer only client asset building (expensive Vite build) to Phase 2.
+	let discovered: Awaited<ReturnType<typeof discoverBlocks>>;
+	try {
+		discovered = await discoverPromise;
+	} catch (err) {
+		throw new BootFatalError(
+			"ui-service.page-manifest",
+			serviceSlug,
+			`Failed to load src/page-manifest.ts. Run scala-tools codegen for the service before boot. Error: ${err instanceof Error ? err.message : err}`,
+			err,
+		);
+	}
+
+	const { components, loaded, skipped } = discovered;
+	if (loaded.length === 0) {
+		throw new BootFatalError(
+			"ui-service.page-manifest",
+			serviceSlug,
+			"Zero Puck components loaded from src/page-manifest.ts. Fix service_install.block_packages or block_schema, regenerate the page manifest, then boot again.",
+		);
+	}
+	if (loaded.length > 0) {
+		log.info(
+			`[two-phase-boot:${serviceSlug}] Discovered ${loaded.length} block(s): ${loaded.join(", ")}`,
+		);
+	}
+	if (skipped.length > 0) {
+		log.warn(
+			`[two-phase-boot:${serviceSlug}] Skipped ${skipped.length} block_schema row(s) ` +
+				`(missing componentPath/componentExport or import failed): ${skipped.join(", ")}`,
+		);
+	}
+
+	// Run boot hooks BEFORE serving - some hooks may register routes and must
+	// run before Hono's matcher is compiled by the first request
+	await runStep("run-boot-hooks", () =>
+		runBootHookList(config, mountRegistry, serviceSlug),
+	);
+
+	// Register page routes with a dynamic handler that delegates to the real handler once Phase 2 completes.
+	// All route paths must be registered before serving to avoid Hono
+	// RegExpRouter compilation issues (matcher becomes immutable).
+	//
+	// CRITICAL: During Phase 1 (minimal app), page requests MUST return 503 BEFORE
+	// attempting to resolve page data. The config object doesn't have proper loadData
+	// set up until Phase 2, and attempting to resolve undefined loadData crashes
+	// resolveDataGraph with "undefined is not an object (evaluating 'Object.keys(spec)')".
+	const registeredPageRoutes = await runStep("register-page-routes", () =>
+		registerPageRoutes({
+			app,
+			config,
+			components,
+			serviceSlug,
+			createPageHandler: (pageConfig) => {
+				// Return a handler that checks if the full app is ready BEFORE processing
+				return async (req, extras) => {
+					// If full app is NOT ready yet, return the branded waking page
+				// (the same pulsating-logo holding page scale-to-zero uses) —
+				// never bare plain text (loading-via-logo-loading).
+					if (!fullAppReady || !realPageHandler) {
+						return new Response(buildWakingPageHtml({}), {
+							status: 503,
+							headers: {
+								"content-type": "text/html; charset=utf-8",
+								"cache-control": "no-store, no-transform",
+								"retry-after": "5",
+							},
+						});
+					}
+					// Full app is ready - delegate to the real handler
+					const handler = realPageHandler(pageConfig);
+					return handler(req, extras);
+				};
+			},
+		}),
+	);
+	const pageRouteCount = registeredPageRoutes.length;
+
+	const steps = Object.entries(stepTimings)
+		.map(([step, ms]) => `${step}=${ms}ms`)
+		.join(" ");
+	// NOTE: several steps run concurrently (speculative preload, init-gate-ttls,
+	// discover-blocks overlap the gate chain), so the step sum exceeds the
+	// wall-clock buildMinimalApp duration. Compare to the boot-ui-service phase
+	// timing in the Boot complete line for the true wall-clock cost.
+	log.info(
+		`[two-phase-boot:${serviceSlug}] buildMinimalApp breakdown (steps overlap) — ${steps}`,
+	);
+
+	log.info(
+		`[two-phase-boot:${serviceSlug}] Minimal app ready: ${apiRouteCount} api route(s), ${wsRouteCount} ws route(s), ${pageRouteCount} page route(s)`,
+	);
+
+	return {
+		app,
+		mountRegistry,
+		apiRouteCount,
+		wsRouteCount,
+		pageRouteCount,
+		config,
+		serviceSlug,
+		databaseUrl,
+		blockPackages,
+		components,
+		loaded,
+		skipped,
+	};
+}
+
+/**
+ * Build the full app with hydration. This adds the expensive operations that
+ * were deferred from the minimal app:
+ * - Client asset building (Vite build)
+ * - Boot hooks (may have expensive initialization)
+ * - Scheduled jobs (can start later)
+ * - pg-boss (can start later)
+ *
+ * This runs in the background after the minimal app is already serving.
+ * NOTE: All routes (including page routes) are already registered in Phase 1,
+ * so we don't need to modify the app here. The app reference stays the same.
+ */
+export async function buildFullApp(
+	minimalResult: MinimalAppResult,
+	deps: PageServerDeps,
+): Promise<FullAppResult> {
+	const log = getAppLogger();
+	const { config, serviceSlug, mountRegistry, components, loaded, app: minimalApp } = minimalResult;
+
+	// Client asset building (expensive: Vite build)
+	await buildClientAssets(serviceSlug);
+
+	// Scheduled jobs
+	startScheduledJobs(config, mountRegistry, serviceSlug);
+
+	// pg-boss (mount for UI services - wasn't mounted in minimal app)
+	const { jobs: pgBossJobs } = await mountPgBoss({
+		databaseUrl: minimalResult.databaseUrl,
+		serviceSlug,
+		packages: config.server_packages ?? [],
+	});
+	if (pgBossJobs.length > 0) {
+		log.info(
+			`[two-phase-boot:${serviceSlug}] pg-boss mounted ${pgBossJobs.length} job(s): ${pgBossJobs.map((j) => j.handlerSlug).join(", ")}`,
+		);
+	}
+
+	log.info(
+		`[two-phase-boot:${serviceSlug}] Full app built: ${loaded.length} block(s), ` +
+			`${Object.keys(components).length} component(s)`,
+	);
+
+	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it
+	setPageHandler(deps.createPageHandler);
+	log.info(
+		`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
+	);
+
+	const resolvedBlocks = loaded.map((slug) => ({
+		slug,
+		packagePath: "block_packages",
+	}));
+
+	return {
+		app: minimalApp, // Same app reference, all routes already registered
+		blocks: resolvedBlocks,
+		routes: [], // Routes already registered in Phase 1
+		pgBossJobs,
+	};
+}
+
+/**
+ * Swap the minimal app for the full app. This atomically replaces the
+ * app reference that Bun.serve is using.
+ */
+export function swapToFullApp(fullApp: Hono, serviceSlug: string): void {
+	const oldLabel = swapApp(fullApp, "full");
+	const log = getAppLogger();
+	log.info(`[two-phase-boot:${serviceSlug}] Swapped from ${oldLabel} app to full app`);
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Shared type definitions for service-boot boot helpers.
+ */
+
+type RendererComponent = (props: Record<string, unknown>) => unknown;
+
+export interface RendererComponentEntry {
+	render: RendererComponent;
+	fields?: Record<string, { type: string }>;
+	/** block_schema.defaults, carried onto the entry by discoverBlocks so
+	 *  buildPuckConfig merges them under authored props at SSR
+	 *  (blocks-fully-programmable). */
+	defaultProps?: Record<string, unknown>;
+}
+
+export interface PageHandlerExtras {
+	htmlTemplate: string;
+	userId?: string;
+	orgId?: string;
+	searchParams?: Record<string, string>;
+	nonce?: string;
+}
+
+export type CreatePageHandler = (
+	config: PageHandlerConfig,
+) => (request: Request, extras: PageHandlerExtras) => Promise<Response>;
+
+export interface PageHandlerConfig {
+	components: Record<string, RendererComponentEntry>;
+	providers?: string[];
+	loadData: (request: Request) => Promise<unknown>;
+	renderMode?: "public" | "portals" | "utility";
+	/**
+	 * Owning service slug — used by the page-server render catch to resolve
+	 * the branded logo on the render-error page. Mirrors service-runtime's
+	 * PageHandlerConfig.
+	 */
+	serviceSlug?: string;
+	/**
+	 * Redirect a signed-in user's `/` to their org-scoped portal dashboard.
+	 * Set only for services serving a `/*` catchall page_route (the portal);
+	 * single-site portal-mode services serve their real page at `/`.
+	 * Mirrors service-runtime's PageHandlerConfig (1.15.82).
+	 */
+	portalHomeRedirect?: boolean;
+}
+
+export type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";