@teamscala/service-boot 0.23.524 → 0.23.526

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";
@@ -122,22 +121,11 @@ export async function registerRegistryPageRoute(
 	for (const routeRow of serviceRoutes) {
 		const routeConfig = routeRow.config;
 		const pattern = routeConfig.pattern;
-		// loader_slug is a page_route runtime value and resource_loader is runtime
-		// data: a row created after this build is exactly the live-edit case this
-		// module serves, so the generated slug union (a build-time snapshot) can
-		// only be asserted, never enforced, here. An unknown slug still fails
-		// closed below (RegistryConfigMissingError skips the route).
 		const loaderSlug = routeConfig.loader_slug as ResourceLoaderKey;
 		const routeProviders = routeConfig.providers ?? baseProviders;
 
 		let loaderConfig: LoaderConfig | null = null;
 		try {
-			// Boot-time warm + validate: a missing row skips the route (warn),
-			// an invalid row fails closed. resource_loader is NOT on the
-			// deploy-time bake list (constitution installer-and-runtime) — it
-			// is re-read per request via readLiveLoaderConfig below — so this
-			// boot read exists ONLY to catch a misconfigured row early, never
-			// as the source of truth for live rendering.
 			loaderConfig = await loadRegistryConfig(
 				"resource_loader",
 				loaderSlug,
@@ -156,22 +144,7 @@ export async function registerRegistryPageRoute(
 			throw err;
 		}
 
-		// Gate for the static-shell graph cache (see module header).
-		const isStaticShell =
-			!routeConfig.resource_type &&
-			!pattern.includes(":") &&
-			!pattern.includes("*");
-
 		const loadData = async (request: Request) => {
-			// resource_loader is runtime data, not deploy-time baked. Re-read it
-			// per request — loadRegistryConfig's SWR cache makes the fresh-window
-			// hit a memory read, not a DB round trip. Throws into the branded
-			// error path on a vanished or invalid row: the boot-time snapshot
-			// must NEVER silently outlive the row it captured. This is the fix
-			// for the loader-row-edits-look-like-they-don't-work defect (every
-			// edit used to need a service restart; the sign-page-with-brand
-			// `agreement` source added at 22:16 still hadn't reached
-			// __PAGE_DATA__.loaderData at 22:29 — 13 minutes, and never).
 			const liveLoaderConfig = await readLiveLoaderConfig(loaderSlug);
 			const url = new URL(request.url);
 			const params = extractUrlParams(pattern, url.pathname);
@@ -179,17 +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,
-				// Folds the live config into the per-route graphKey so a row edit
-				// invalidates the cached graph immediately (the graph is a
-				// function of the config; without this the SWR graph cache
-				// would still hold the old shape until its fresh window lapsed).
-				configFingerprint: fingerprintLoaderConfig(liveLoaderConfig),
 			});
 			const { sessionUserId, sessionOrgId } = await stampSessionContext(
 				resolved,
@@ -203,8 +168,6 @@ export async function registerRegistryPageRoute(
 				resolved,
 				gateCookie,
 				Date.now(),
-				routeConfig.assistant,
-				regionSlots,
 			);
 			const meta = buildMetaFromContext(routeConfig.meta_context, resolved);
 			await applySignInBrandOverride(resolved, request);
@@ -216,13 +179,6 @@ export async function registerRegistryPageRoute(
 		) {
 			meta.title = pageMetaTitle.trim();
 		}
-		// Org-prefixed page titles (feature flag page-title-org-prefix, read
-		// LIVE per request — feature flags are never cached). The title prefix
-		// is the OWNING ORG'S name, never the internal website label
-		// ("Public Pages: <subject>" on a client-facing document was the
-		// defect; operator ruling 2026-08-17). Absent or unreadable flag ⇒
-		// legacy <website.name>: <subject> derivation — the switch fails toward
-		// the pre-flag behaviour, and flipping it back is one registry edit.
 		let orgTitlePrefix = false;
 		try {
 			orgTitlePrefix = (
@@ -233,14 +189,8 @@ export async function registerRegistryPageRoute(
 				)
 			).enabled;
 		} catch {
-			// Flag row absent — legacy derivation.
 		}
 			const themeParam = url.searchParams.get("theme");
-			// ?theme is the EMBED override — only honor it when this page is
-			// actually framed (a form/quiz in a GPT tool panel, sec-fetch-dest:
-			// iframe). A DIRECT visit carrying ?theme= (e.g. copied from a GPT
-			// embed URL) must NOT override the org's DB theme — what the visitor
-			// sees is org-driven, never URL-driven.
 			const isFramedEmbed =
 				request.headers.get("sec-fetch-dest") === "iframe";
 			const themeOverride =
@@ -257,12 +207,6 @@ export async function registerRegistryPageRoute(
 				themeOverride,
 				orgTitlePrefix,
 			);
-			// The matched route params (extractUrlParams + host/path) ride the
-			// per-request pageData so the SSR resolve ctx can scope PUBLIC
-			// block data per request — data_source loaders read ctx.pathParams
-			// (query-data-source); without them a public table would return
-			// every person's rows. Attached AFTER the graph cache (per-request,
-			// never cached with the graph).
 			(pageData as Record<string, unknown>).pathParams = params;
 			const panelSlug = new URL(request.url).searchParams.get("panel");
 			await attachPanelPage(pageData as Record<string, unknown>, panelSlug);
@@ -284,39 +228,22 @@ export async function registerRegistryPageRoute(
 			await applyBrandOrgPath(
 				pageData as Record<string, unknown>,
 				resolved,
-				// brand_org_path is the row schema's own field now — the derived
-				// type sees it, so the narrowing cast the mirror needed is gone.
 				routeConfig.brand_org_path,
 				params,
 				serviceSlug,
 			);
 			warnUncoveredBlocks(pageData, components, serviceSlug, params.path, log);
-			// Detached (NOT awaited into the response). prefetchAiChatSession -> createOrRestore is DB-heavy (~1.1s), per-user, and uncached, and was
-			// awaited on EVERY loadData — the dominant board loadMs cost (confirmed
-			// aiChatPrefetch=1145ms = the full loadMs). Fire it in the background so
-			// it still warms the server-side session (users who open chat find it
-			// warm via their live fetch) without blocking the page response. The SSR
-			// chat seed (pageData.aiChatSession) is sacrificed — chat opens with a
-			// live fetch instead of SSR-instant — the right trade: most loads never
-			// open chat, so eager-awaited prefetch was the waste. orgId is the
-			// URL-derived org (resolveAiOrgId) — see prefetch-org-id.ts for why
-			// segment 1 is preferred over segment 0.
 			const aiOrgId = resolveAiOrgId(new URL(request.url).pathname);
 			void prefetchAiChatSession(resolved, sessionUserId, aiOrgId).catch((err) =>
 				log.warn(
 					`[scala-install:${serviceSlug}] background ai-chat prefetch failed: ${err instanceof Error ? err.message : err}`,
 				),
 			);
-			// Proposal pages: resolve the {{approvalEmail}} button token to the
-			// org's registered company email (creator email as fallback).
 			if (resolved.proposal) {
 				await applyApprovalEmailToken(
 					pageData as Record<string, unknown>,
 					resolved.proposal as { created_by?: string } | undefined,
 				);
-				// Stash the partner logo from the partnerOrg loader source (CRM record
-				// loaded by partner_id) onto pageData.partnerLogo — header fills
-				// automatically, no inline body-Hero prop needed.
 				applyPartnerBrand(
 					pageData as Record<string, unknown>,
 					resolved.partnerOrg as
@@ -324,10 +251,6 @@ export async function registerRegistryPageRoute(
 						| undefined
 						| null,
 				);
-				// Auto-resolve the client's company logo from the clientOrg loader
-				// source (contact → company → crm_organisations.logo_url). Only
-				// injects when the Hero's clientLogo prop is empty — a manually set
-				// logo always wins.
 				applyClientLogo(
 					pageData as Record<string, unknown>,
 					resolved.clientOrg as
@@ -353,10 +276,6 @@ export async function registerRegistryPageRoute(
 			providers: routeProviders,
 			renderMode: routeRenderMode,
 			loadData: loadData as never,
-			// The portal home redirect follows the DECLARED portal_scoped service
-		// fact (see RegistryRouteArgs.portalScoped) — a signed-in user at "/" of
-		// an org-scoped portal belongs at /<websiteId>/<orgId>/dashboard; a
-		// flat-path service (the fleet dashboard) serves its real page at "/".
 			portalHomeRedirect: portalScoped,
 			serviceSlug,
 		});
@@ -374,10 +293,6 @@ export async function registerRegistryPageRoute(
 		});
 
 		registeredPatterns.push(pattern);
-		// Boot-validated snapshot (the LIVE read is per request — see
-		// readLiveLoaderConfig); name the shape so a misconfigured row is
-		// visible at boot, and note the live contract so "my loader edit
-		// didn't take effect" routes to the graph SWR window, not a restart.
 		log.info(
 			`[scala-install:${serviceSlug}] registered registry page route "${pattern}" → resource_loader "${loaderSlug}" (boot-validated: ${describeCapturedLoaderConfig(loaderConfig)}; re-read live per request)`,
 		);

package/src/register-static-assets.ts

@@ -14,10 +14,6 @@ import { isLoopbackHost } from "@teamscala/os/observability/loopback-host";
 import { handleAssetProxy } from "./asset-proxy";
 import { resolveBrandFaviconPath, warmBrandFaviconCache } from "./resolve-brand-favicon";
 
-// Served ONLY when the org has no brand favicon, so the correct colour is the
-// platform brand default rather than a literal. This changes the generic
-// fallback mark from indigo to the canonical slate; any org with its own
-// favicon is unaffected (resolveBrandFaviconPath wins before this is reached).
 const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="${FALLBACK_PRIMARY_COLOR}"/><text x="16" y="23" text-anchor="middle" font-size="20" font-family="system-ui" fill="white">S</text></svg>`;
 
 export async function registerStaticAssets(
@@ -25,9 +21,6 @@ export async function registerStaticAssets(
 	serviceSlug: string,
 	brandOrg?: string,
 ): Promise<void> {
-	// Warm the brand-favicon cache at boot — the S3 existence probe is a 6-21s
-	// cold call that otherwise stalls the first /favicon.ico after every
-	// restart. Fire-and-forget; never blocks boot or a request.
 	warmBrandFaviconCache(brandOrg);
 
 	app.get("/health", (c) =>
@@ -38,16 +31,6 @@ export async function registerStaticAssets(
 		}),
 	);
 
-	// Localhost-gated heap-attribution probe — the heapSize-vs-RSS split (JS heap
-	// vs native: OTel/Prisma-engine/buffers/compiled code) plus the top object
-	// types by count. Read-only, no secrets; gated to a localhost Host so it never
-	// answers over the public domain. Registered here (before auth + page routes)
-	// so it is reachable on every service kind, like /health
-	// (`verify-via-127.0.0.1`, sibling of `runtime-metrics-via-railway-cli`).
-	//
-	// The payload shape lives in @teamscala/os so standalone `Bun.serve` daemons
-	// (scala-guard) answer this probe identically — `scala-tools heap <slug>` must
-	// not mean different things depending on which process replied.
 	app.get("/_heap", async (c) => {
 		if (!isLoopbackHost(c.req.header("host"))) return c.json({ error: "localhost only" }, 403);
 		try {
@@ -61,16 +44,6 @@ export async function registerStaticAssets(
 		}
 	});
 
-	// Build-id: the content hash of the CURRENT client bundle, read FRESH from the asset manifest on every call (never a process-pinned copy) so a
-	// post-restart rebuild reports its new id immediately. The client self-heal (page-client/boot/build-self-heal) polls this on tab refocus; if it differs
-	// from the build the tab booted with, a new build shipped and the open tab is
-	// stale → it reloads. no-store HTML + immutable hashed assets already prevent
-	// staleness on every FRESH load; this is what closes the one remaining hole —
-	// a tab left OPEN across a deploy, holding old HTML pinned to old asset
-	// hashes, with nothing telling it to re-fetch (the "my tablet still shows the
-	// old broken page" class). The id derives from hydratePath exactly as the
-	// SSR-stamped window.__SCALA_BUILD__ does (render-page-html), so they can
-	// never structurally disagree and trigger a reload loop.
 	app.get("/api/build-id", async (c) => {
 		const path = join(process.cwd(), "dist", "client", "asset-manifest.json");
 		let build = "dev";
@@ -84,10 +57,6 @@ export async function registerStaticAssets(
 		return c.json({ build }, 200, { "cache-control": "no-store" });
 	});
 
-	// A branded host (service_install.config.brand_org) never serves the
-	// generic platform mark — both favicon paths resolve the owning org's
-	// icon from its asset store; the generic SVG remains only for hosts
-	// with no declared owner (multi-tenant / infra).
 	app.get("/favicon.svg", async (_c) => {
 		const brand = await resolveBrandFaviconPath(brandOrg);
 		if (brand)
@@ -105,18 +74,10 @@ export async function registerStaticAssets(
 
 	app.get("/favicon.ico", async (c) => {
 		const brand = await resolveBrandFaviconPath(brandOrg);
-		// 302 (not 301): the brand asset is row-driven and must stay
-		// re-resolvable — a permanent redirect would pin stale targets in
-		// browser caches, the exact failure this route exists to end.
-		// cache-control lets the browser cache the redirect (5min) so it
-		// doesn't re-hit the origin per page load — mirrors /favicon.svg.
 		c.header("cache-control", "public, max-age=300");
 		return c.redirect(brand ?? "/favicon.svg", 302);
 	});
 
-	// Same-origin S3 asset proxy: /api/assets/<key> → bucket. Public,
-	// immutable cache, no auth. Canonical URL form for every logo, favicon,
-	// avatar, uploaded asset — emitted by toAssetPath() in @teamscala/core-ui/theme.
 	app.get("/api/assets/*", (c) => handleAssetProxy(c.req.raw));
 
 	app.use("/assets/*", etag());
@@ -137,12 +98,6 @@ export async function registerStaticAssets(
 		return c.notFound();
 	});
 
-	// Extension auto-update files (.crx + updates.xml) served from ./ext/.
-	// Chrome's extension updater fetches updates.xml over plain HTTPS with no
-	// auth, so this route is registered before any auth gate and on every UI
-	// service. Files are served with short-lived cache so updates propagate
-	// promptly. The ./ext/ directory is gitignored and populated by the
-	// extension build pipeline.
 	app.get("/ext/*", async (c) => {
 		const filePath = join(
 			process.cwd(),

package/src/resolve-brand-favicon.ts

@@ -37,15 +37,6 @@ export async function resolveBrandFaviconPath(
 	});
 }
 
-/**
- * Eagerly resolve + cache the favicon at boot so the FIRST user request never
- * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
- * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
- * store takes 6s locally / up to 21s in prod, and the in-process cache resets
- * on every restart (deploys, dep-sync). Without warming, the first
- * /favicon.ico after each restart stalls for that duration (operator-reported
- * 23s). Fire-and-forget — runs in the background during boot, never blocks.
- */
 export function warmBrandFaviconCache(brandOrg: string | undefined): void {
 	if (!brandOrg) return;
 	void resolveBrandFaviconPath(brandOrg);

package/src/resolve-service-port.ts

@@ -4,11 +4,8 @@
  */
 
 export interface PortResolution {
-	/** The port to bind. */
 	port: number;
-	/** Which source decided it — for the boot log, so the choice is auditable. */
 	source: "env" | "service_routing";
-	/** Set when PORT disagreed with the row; the caller logs it. */
 	conflict?: { envPort: number; declaredPort: number };
 }
 
@@ -16,14 +13,6 @@ function isBindablePort(value: number | undefined): value is number {
 	return value !== undefined && Number.isFinite(value) && value > 0 && value <= 65535;
 }
 
-/**
- * @param envPort   parsed PORT env, or undefined when unset/unparseable
- * @param declaredPort `service_routing.local_port`, or undefined when the
- *                     service has no routing row (the Railway-only case)
- * @param isRailway  true when booting inside Railway (caller derives from
- *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
- *                   regardless of the row, because Railway healthchecks it
- */
 export function resolveServicePort(
 	envPort: number | undefined,
 	declaredPort: number | undefined,

package/src/resolve-theme-mode.ts

@@ -5,7 +5,6 @@
 
 export interface ResolvedThemeMode {
 	theme: "light" | "dark";
-	/** True iff the mode came from the ?theme= embed override. */
 	embedded: boolean;
 }
 
@@ -14,15 +13,8 @@ function asMode(value: unknown): "light" | "dark" | undefined {
 }
 
 export function resolveThemeMode(opts: {
-	/** Request URL (or its href) — read for the ?theme= embed override. */
 	url?: URL | string | null;
-	/**
-	 * Explicit embed override, when the caller already extracted ?theme= from
-	 * the URL upstream (e.g. a pure data-shaper that has no Request). Same
-	 * effect and priority as the URL form.
-	 */
 	override?: unknown;
-	/** Theme candidates in priority order: rootTheme, brandTheme, websiteTheme. */
 	candidates?: Array<unknown>;
 }): ResolvedThemeMode {
 	let override = asMode(opts.override);

package/src/resolvers/app-header.ts

@@ -3,7 +3,6 @@
  * @status handwritten
  */
 
-/** AEST calendar date (the operator timezone) as `YYYY-MM-DD`. */
 function aestCalendarDate(now: Date): string {
 	return new Intl.DateTimeFormat("en-CA", {
 		timeZone: "Australia/Sydney",

package/src/resolvers/fetch-org-brand.ts

@@ -6,7 +6,6 @@ import { fetchOrgBrand } from "@teamscala/resolver-engine/data-resolvers/fetch-o
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { ResolverArgs } from "./portal-route-paths.ts";
 
-/** A null brand renders a page with no logo, colours or name — so each failure names which of the three it was. */
 export async function fetchOrgBrandWithFallback({ input, client }: ResolverArgs): Promise<unknown> {
 	const orgId = input.orgId as string | undefined;
 	const fallbackOrgId = input.fallbackOrgId as string | undefined;

package/src/resolvers/portal-route-paths.ts

@@ -2,23 +2,6 @@
  * @system service-boot
  * @status handwritten
  */
-/**
- * Extract the organisation id from a portal-shaped callback/path — the single
- * authority for "which segment is the org" so the sign-in brand resolver and the
- * route resolver cannot drift on the answer (portal-branding-resolves-page-org-first).
- *
- * The canonical portal shape is `/<websiteId>/<orgId>/<path>` — the org is
- * segment 1, NOT segment 0. Reading segment 0 fed the WEBSITE id into brand
- * resolution, which resolved no org and fell back to the super-admin org — the
- * exact cross-tenant mis-branding this exists to prevent (bind-page-handler.ts,
- * found 2026-07-21).
- *
- * Single-UUID hosts keep segment 0 unchanged: scala-projects routes `/<orgId>/…`
- * and proposal/form/quiz hosts route `/<resourceId>/…` (a non-org first segment
- * that resolves to no brand and falls back as before — no regression, only the
- * correct-org improvement for the two-UUID portal shape). Returns undefined when
- * neither leading segment is a UUID.
- */
 
 export interface ResolverArgs {
 	input: Record<string, unknown>;

package/src/resource-not-found.ts

@@ -15,16 +15,7 @@ const RESOURCE_LABELS: Record<string, string> = {
 
 export class PrimaryResourceMissingError extends Error {
 	readonly resourceType: string;
-	// HTTP status for the holding page. 404 for a genuinely missing/invalid
-	// resource (a dead /:id link); 200 for the bare root of a UUID-driven site
-	// ("no <resource> selected") — the root is a valid landing, not an error,
-	// and kind:ui services must answer GET / with 200 (verify-prod-persistent-slot).
 	readonly httpStatus: number;
-	// A page ROW exists but has zero content blocks — a content gap, not a dead
-	// link (operator ruling 2026-07-21: "if the page is empty, it should have a
-	// Puck block that says this page is empty... and then take me home"). The
-	// floor renders the "This page is empty" surface (200) instead of the dead-
-	// link "doesn't exist" surface (404). Distinct from a dead link (no row).
 	readonly empty: boolean;
 	constructor(resourceType: string, httpStatus = 404, opts?: { empty?: boolean }) {
 		super(`primary resource "${resourceType}" not found`);
@@ -39,23 +30,10 @@ export function buildResourceNotFoundResponse(
 	resourceType: string,
 	logoUrl?: string | null,
 	status = 404,
-	// Optional 4th arg keeps the existing 3-arg call sites working while letting
-	// the page binder add a "Take me home" action (operator-requested) and the
-	// empty-page variant.
 	opts?: { homeUrl?: string; empty?: boolean },
 ): Response {
 	const label = RESOURCE_LABELS[resourceType] ?? "page";
-	// Single-owner hosts show the owner's wordmark; multi-tenant hosts
-	// (no brand_org — a dead id's org is unknowable) stay platform-neutral.
-	// The helper emits the inline data-URI src with reserved width+height
-	// (logos-inline-on-branded-server-pages).
 	const logoImg = brandLogoImgTag(logoUrl, { height: 40, width: 160 });
-	// Three surfaces share this one floor (resource-not-found-is-the-root-floor):
-	//   200 root  — the BARE ROOT of a UUID-driven host ("no <resource> selected").
-	//   404 dead  — a content path with NO page row (a deleted/moved page, e.g.
-	//              /roadmap) OR a dead /:id: a link that genuinely doesn't resolve.
-	//   200 empty — a page ROW exists but has zero blocks (a content gap, not a
-	//              dead link): "This page is empty", still take-me-home.
 	const isEmpty = opts?.empty === true;
 	const isRoot = status === 200 && !isEmpty;
 	const title = isEmpty ? "Nothing here yet" : isRoot ? `No ${label} here` : "Not found";
@@ -71,8 +49,6 @@ export function buildResourceNotFoundResponse(
 			   sent to view it — there&rsquo;s nothing to see at the bare address.`
 			: `The page you&rsquo;re looking for may have been moved or removed, or the
 			   link may be incomplete.`;
-	// "Take me home" — operator-requested action on every not-found/empty surface.
-	// Omitted on the bare-root landing (it IS home). Defaults to the host root.
 	const homeUrl = opts?.homeUrl ?? "/";
 	const homeLink = isRoot
 		? ""

package/src/select-service-routes.ts

@@ -5,17 +5,10 @@
 
 import { toCapabilitySlug } from "./capability-slug.ts";
 
-/** The shape this module needs from a loaded page_route row. */
 export interface SelectableRoute {
 	config: { pattern: string; service: string };
 }
 
-/**
- * Specificity rank for registration order. Hono matches by registration
- * order, so `/*` (the portal catchall) registered before `/sign-in` would
- * swallow the sign-in page and render it inside the PortalTemplate instead
- * of the standalone PublicTemplate shell.
- */
 function comparePatternSpecificity(a: string, b: string): number {
 	// Wildcard `/*` goes last.
 	if (a === "/*") return 1;
@@ -28,13 +21,6 @@ function comparePatternSpecificity(a: string, b: string): number {
 	return 0;
 }
 
-/**
- * The page_route rows this service serves, in registration order.
- *
- * `serviceSlug` is the deployable identity of the calling lane; both sides
- * of the join normalize through `toCapabilitySlug`, so a row may name either
- * the capability or a deployable form and both lanes resolve the same set.
- */
 export function selectServiceRoutes<T extends SelectableRoute>(
 	allRoutes: readonly T[],
 	serviceSlug: string,

package/src/theme-fonts-link.ts

@@ -9,15 +9,11 @@ interface ThemeFontsConfig {
 	fonts?: Record<string, string>;
 }
 
-/** The primary family name of a CSS font stack: "Inter, sans-serif" →
- * "Inter"; "Playfair Display" → "Playfair Display". */
 export function primaryFontFamily(stack: string): string {
 	const first = stack.split(",")[0] ?? "";
 	return first.trim().replace(/^['"]|['"]$/g, "");
 }
 
-/** The declared theme families, deduplicated by primary family, in row
- * order (body, heading, manuscript, mono…). Empty when the row is absent. */
 export function themeFontFamilies(): string[] {
 	try {
 		const config = getEntryConfig<ThemeFontsConfig>("css_theme", "default");
@@ -37,7 +33,6 @@ export function themeFontFamilies(): string[] {
 	}
 }
 
-/** The <link> tag loading every declared theme family, or "" when none. */
 export function themeFontsLink(): string {
 	const families = themeFontFamilies();
 	if (families.length === 0) return "";

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

@@ -3,52 +3,8 @@
  * @status handwritten
  */
 
-/**
- * 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.
- */
 
-	// Client asset building (expensive: Vite build).
-	//
-	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
-	// This was awaited unguarded, so a throw here aborted buildFullApp before
-	// mountPgBoss ran, and the caller's catch logged
-	// "Failed to build full app, continuing with minimal app" — which reads as a
-	// UI-only degradation while having silently killed every pg-boss handler on
-	// the service.
-	//
-	// Measured 2026-07-30: a stale @teamscala/portal-ui artifact still importing
-	// the retired @teamgbg scope threw ENOENT on a missing theme CSS file in
-	// scala-agents. Zero "scheduledJobs DONE" lines appeared for ~20 minutes
-	// across repeated boots, the pane-outbox drain never mounted, and the
-	// operator's WhatsApp assistant went silent — because of a stylesheet. The
-	// service stayed `online` and healthy throughout, so nothing surfaced it.
-	//
-	// The steps after this one do not depend on client assets: pg-boss needs the
-	// registry and the DB, not a bundle. Ordering it behind a Vite build was
-	// incidental, so the coupling was never intended.
 
-	// pg-boss (mount for UI services - wasn't mounted in minimal app)
-	//
-	// Wrapped for the SAME reason buildClientAssets above is, in the other
-	// direction: a background-work failure must not cost the page. Unwrapped,
-	// anything mountPgBoss throws propagates out of the full-app build, the
-	// caller falls back to the MINIMAL app, and the service serves 0 api routes
-	// with /health 503 — so the tunnel health check fails and the site is
-	// unreachable from outside while localhost answers in 0.1s.
-	//
-	// Measured 2026-08-31 on scala-projects: a deps refresh moved pg-boss to a
-	// build expecting a newer shared pgboss schema than the database carried, its
-	// migration threw, and an outage of every page followed from a scheduled-job
-	// dependency. Jobs are the degradable half; pages are not.
 
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
@@ -78,9 +34,6 @@ export async function buildFullApp(
 		await buildClientAssets(serviceSlug);
 		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
 	} catch (error) {
-		// Loud but non-fatal: the tombstone manifest written by buildClientAssets
-		// already makes SSR serve the prior bundle, so degrading here costs the
-		// new bundle, never the background work.
 		log.error(
 			`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets FAILED — continuing to scheduled jobs and pg-boss (a client-asset failure must not stop background work)`,
 			{ error: error instanceof Error ? error.message : String(error) },
@@ -107,23 +60,6 @@ export async function buildFullApp(
 		);
 	}
 
-	// The readiness flip is gated on a VERIFIED client build, never on "phase 2
-	// got this far". buildClientAssets's failure above is deliberately non-fatal
-	// for background work — but a deployment whose client build never ran (or
-	// whose tombstone names unbuilt files) must not flip ready and serve pages:
-	// every served asset URL would 404 while /health and the deploy report ok.
-	// Measured 2026-09-01: proposals.scala.business served a client-facing
-	// proposal unstyled while Railway reported SUCCESS, because the phase-1
-	// catch let boot continue past the build and the flip never checked the
-	// build's outcome (`a-component-may-not-report-a-state-it-has-not-verified`).
-	// The throw lands in ui-service's boot.client-build-failed catch, which
-	// keeps the minimal app: pages and /health stay 503 (cleanly unavailable)
-	// while the pg-boss jobs mounted above KEEP RUNNING. On Railway the
-	// healthcheck (healthcheckPath: /health) then fails and the previous good
-	// deployment keeps traffic — the deploy reports FAILED, never SUCCESS.
-	// readiness-gated-boot: a service is "fully-ready or cleanly-unavailable";
-	// a UI service that cannot serve its bundle is not ready
-	// (`liveness-by-capability-not-process-existence`).
 	const clientBuild = await verifyClientBuildAssets();
 	if (!clientBuild.ok) {
 		throw new Error(
@@ -139,20 +75,12 @@ export async function buildFullApp(
 			`${Object.keys(components).length} component(s)`,
 	);
 
-	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it.
-	// Client-only services (render_mode=client) have no SSR page handler — skip
-	// (they serve via the client bundle, never SSR). Guarded so undefined is a
-	// no-op rather than a crash.
 	if (deps.createPageHandler) {
 		setPageHandler(deps.createPageHandler);
 		log.info(
 			`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
 		);
 	} else {
-		// The full app IS built — this service simply never renders server-side,
-		// so readiness is flipped directly rather than as a side effect of
-		// registering an SSR handler that will never exist. Without this a
-		// client-only service is permanently un-ready (see markFullAppReady).
 		markFullAppReady();
 		log.info(
 			`[two-phase-boot:${serviceSlug}] Client-only mode (render_mode=client) — no SSR page handler registered`,
@@ -172,10 +100,6 @@ export async function buildFullApp(
 	};
 }
 
-/**
- * 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();