@teamscala/service-boot 0.23.430 → 0.23.432

package/src/handlers/upstream-issue-sync.ts

@@ -32,6 +32,7 @@ import { spawn } from "@teamscala/os/spawn";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
+import { createCache } from "@teamscala/cache/create-cache";
 
 interface GhIssue {
 	state: string;
@@ -52,12 +53,18 @@ interface CapturedResponse {
 }
 
 const DEFAULT_GH_TIMEOUT_MS = 20_000;
-let cachedGhTimeoutMs: number | undefined;
+const ghTimeoutCache = createCache<number>("service-boot:gh-timeout", {
+	ttlMs: Number.POSITIVE_INFINITY,
+	maxSize: 1,
+});
+
 async function getGhTimeoutMs(): Promise<number> {
-	if (cachedGhTimeoutMs !== undefined) return cachedGhTimeoutMs;
+	const hit = ghTimeoutCache.get("default");
+	if (hit !== undefined) return hit;
 	const row = await loadRegistryConfig("config", "upstream-issue-sync", v.looseObject({}));
-	cachedGhTimeoutMs = (row?.gh_timeout_ms as number | undefined) ?? DEFAULT_GH_TIMEOUT_MS;
-	return cachedGhTimeoutMs;
+	const timeoutMs = (row?.gh_timeout_ms as number | undefined) ?? DEFAULT_GH_TIMEOUT_MS;
+	ghTimeoutCache.set("default", timeoutMs);
+	return timeoutMs;
 }
 const EXCERPT_MAX = 160;
 

package/src/handlers/whatsapp-liveness.ts

@@ -32,6 +32,7 @@ import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
 import { detectLivenessTransitions, type WhatsAppDeviceState } from "./whatsapp-liveness-logic.ts";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
+import { createCache } from "@teamscala/cache/create-cache";
 
 /** In-process last-known device state, keyed by GOWA device id. */
 const lastKnown = new Map<string, string>();
@@ -46,18 +47,27 @@ interface GowaListDevicesResponse {
 	}>;
 }
 
-let cachedSystemIdentity: { userId: string | undefined; organisationId: string | undefined } | undefined;
+const systemIdentityCache = createCache<{
+	userId: string | undefined;
+	organisationId: string | undefined;
+}>("service-boot:whatsapp-liveness-system-identity", {
+	ttlMs: Number.POSITIVE_INFINITY,
+	maxSize: 1,
+});
+
 /** The system-caller identity for platform-action tool dispatches — shared by
  * the sibling handlers that dispatch GOWA reads through the central /mcp
  * (messaging-send-recording-watch reconcile sweep). */
 export async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
-	if (cachedSystemIdentity) return cachedSystemIdentity;
+	const hit = systemIdentityCache.get("default");
+	if (hit) return hit;
 	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
-	cachedSystemIdentity = {
+	const identity = {
 		userId: row?.system_user_id as string | undefined,
 		organisationId: row?.system_org_id as string | undefined,
 	};
-	return cachedSystemIdentity;
+	systemIdentityCache.set("default", identity);
+	return identity;
 }
 
 export async function pollWhatsAppLiveness({

package/src/install-harness.ts

@@ -2,7 +2,7 @@
  * @system server-boot
  * @status handwritten
  * @edit edit directly
- * @indivisible-unit
+ * @indivisible-unit owner=unassigned reason=81 lines; pre-2026-08-27 exemption, unreviewed
  *
  * Install harness — sandbox-mounts each declared package and captures
  * registry.require() calls via AsyncLocalStorage. Validates all required

package/src/install-logging.ts

@@ -2,7 +2,7 @@
  * @system server-boot
  * @status handwritten
  * @edit edit directly
- * @indivisible-unit
+ * @indivisible-unit owner=unassigned reason=188 lines; pre-2026-08-27 exemption, unreviewed
  *
  * One-call install of the entire logging pipeline. After installLogging()
  * runs, every error in the service — process-level, HTTP middleware, Hono

package/src/mount-orpc-router.test.ts

@@ -8,8 +8,8 @@
  * service, so production boot must fail before it can report healthy.
  */
 
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { afterEach, describe, expect, mock, test } from "bun:test";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { mountOrpcRouter } from "./mount-orpc-router.ts";
@@ -17,22 +17,19 @@ import { mountOrpcRouter } from "./mount-orpc-router.ts";
 const originalCwd = process.cwd();
 const tempDirs: string[] = [];
 
-afterEach(() => {
+afterEach(async () => {
 	process.chdir(originalCwd);
 	for (const directory of tempDirs.splice(0)) {
-		rmSync(directory, { recursive: true, force: true });
+		await rm(directory, { recursive: true, force: true });
 	}
 });
 
 describe("mountOrpcRouter generated-artifact seam", () => {
 	test("fails when schema exists but generated router is absent", async () => {
-		const service = mkdtempSync(join(tmpdir(), "mount-orpc-router-test-"));
+		const service = await mkdtemp(join(tmpdir(), "mount-orpc-router-test-"));
 		tempDirs.push(service);
-		mkdirSync(join(service, "prisma"), { recursive: true });
-		writeFileSync(
-			join(service, "prisma/schema.prisma"),
-			'datasource db { provider = "postgresql" }',
-		);
+		await mkdir(join(service, "prisma"), { recursive: true });
+		await Bun.file(join(service, "prisma/schema.prisma")).write('datasource db { provider = "postgresql" }');
 		process.chdir(service);
 
 		await expect(
@@ -43,4 +40,53 @@ describe("mountOrpcRouter generated-artifact seam", () => {
 				" but the generated ORPC router is missing",
 		);
 	});
+
+	test("the configured getMcpGatewayUrl returns undefined without throwing (ctx regression)", async () => {
+		// Regression: the previous form read an out-of-scope `ctx` (commit
+		// c39d279) and threw ReferenceError on first invoke. A getter that
+		// crashes when called can hide indefinitely — the regression is a test
+		// that actually CALLS it. Returning undefined explicitly matches what
+		// callers (sdk-mcp-forwarder) already handle: an absent gateway URL
+		// means "SDK tools unusable in this service".
+		const service = await mkdtemp(join(tmpdir(), "mount-orpc-router-test-"));
+		tempDirs.push(service);
+		await mkdir(join(service, "prisma/generated/orpc/routers"), {
+			recursive: true,
+		});
+		await Bun.file(join(service, "prisma/schema.prisma")).write(
+			'datasource db { provider = "postgresql" }',
+		);
+		await Bun.file(
+			join(service, "prisma/generated/orpc/routers/index.ts"),
+		).write(
+			"export const router = { healthz: { health: async () => ({ ok: true }) } };\n",
+		);
+		process.chdir(service);
+
+		// Stub the collaborators the mount reaches BEFORE configureToolExecutor
+		// — the point is to capture the opts object and call the getter.
+		const capture: { getMcpGatewayUrl?: () => unknown } = {};
+		mock.module("@teamscala/orpc/app-router", () => ({
+			getAppRouter: async () => ({
+				healthz: { health: async () => ({ ok: true }) },
+			}),
+		}));
+		mock.module("@teamscala/orpc/configure", () => ({
+			getPrisma: () => ({}),
+		}));
+		mock.module("@teamscala/tool-executor/configure", () => ({
+			configure: (opts: { getMcpGatewayUrl?: () => unknown }) => {
+				capture.getMcpGatewayUrl = opts.getMcpGatewayUrl;
+			},
+		}));
+
+		const app = { post: () => {} };
+		await mountOrpcRouter(app as never, "scala-mcp");
+
+		expect(typeof capture.getMcpGatewayUrl).toBe("function");
+		// THE regression: invoking the getter must not throw.
+		expect(() => capture.getMcpGatewayUrl!()).not.toThrow();
+		// And it returns undefined — explicit, never a ReferenceError.
+		expect(capture.getMcpGatewayUrl!()).toBeUndefined();
+	});
 });

package/src/mount-orpc-router.ts

@@ -9,7 +9,6 @@
  * routers with custom routers registered via registerCustomRouter().
  */
 
-import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { registerFnRouters } from "./fn-routers/index.ts";
@@ -45,8 +44,8 @@ export async function mountOrpcRouter(
 	// reserved for GENUINE mount failures (router present but fails to load).
 	// A service that SHOULD have a router but doesn't is a codegen gap caught by
 	// API verification, not a boot warning.
-	if (!existsSync(routerPath)) {
-		if (existsSync(schemaPath)) {
+	if (!await Bun.file(routerPath).exists()) {
+		if (await Bun.file(schemaPath).exists()) {
 			throw new Error(
 				`[scala-install:${serviceSlug}] Prisma schema exists at ${schemaPath} ` +
 					`but the generated ORPC router is missing at ${routerPath}. ` +
@@ -84,17 +83,32 @@ export async function mountOrpcRouter(
 		const { configure: configureToolExecutor } = await import(
 			"@teamscala/tool-executor/configure"
 		);
+		// The host-command-bus collaborators arrive here (the boot layer) —
+		// tool-executor cannot import its tier-2 siblings statically
+		// (vertical-dependency-only: a same-tier edge). Resolved eagerly at
+		// mount so the injected factories stay synchronous; the modules are
+		// small and their postgres dependency is already loaded by the db
+		// primitive.
+		const [{ createHostCommandInvoker }, { getCallerContext }, { decryptSecretConfig }] =
+			await Promise.all([
+				import("@teamscala/host-command-bus/invoker"),
+				import("@teamscala/mcp-multi-session/caller-context"),
+				import("@teamscala/encryption/crypto/secret-config"),
+			]);
 		configureToolExecutor({
 			getAppRouter: () => getAppRouter(),
 			getPrisma: () => getConfiguredPrisma(),
 			// Central MCP gateway URL — sdk:* tool calls from any non-host service
 			// forward here (scala-mcp owns every @teamscala/api-* adapter per
-			// operator ruling 2026-08-26). The HTTP layer reads from the
-			// per-request config surface (the same place getAppRouter / getPrisma
-			// are resolved from), not the ambient environment, to honour
-			// `configured-primitives`.
-			getMcpGatewayUrl: () =>
-				(ctx as { config?: { MCP_GATEWAY_URL?: string } }).config?.MCP_GATEWAY_URL,
+			// operator ruling 2026-08-26). Returns undefined explicitly: callers
+			// (sdk-mcp-forwarder) treat absent as "SDK tool unusable in this
+			// service" and refuse with that message. The previous form read an
+			// out-of-scope `ctx` (c39d279) and would have thrown ReferenceError
+			// on first invoke instead of returning undefined.
+			getMcpGatewayUrl: () => undefined,
+			createHostCommandInvoker: (config) => createHostCommandInvoker(config as never),
+			getCallerContext: () => getCallerContext(),
+			decryptSecretConfig: (raw) => decryptSecretConfig(raw as never),
 		});
 
 		const resolveUser = async (headers: Headers) => {

package/src/mount-server-packages.ts

@@ -10,6 +10,23 @@
  * register-ws-routes / run-boot-hook-list / start-scheduled-jobs.
  */
 
+/**
+ * Speculatively import every server_package's mount module so Bun compiles
+ * the module graphs into its cache NOW, overlapping the (CPU-bound)
+ * compilation with whatever I/O the caller runs next. When mountServerPackages
+ * later imports the same paths they hit the cache (instant).
+ *
+ * Same pattern as create-boot-pipeline's speculative preloads — the
+ * cross-internet DB I/O in the gate chain (~3.4s) is dead time the compiler
+ * can use. Best-effort + non-fatal: a failed import here (wrong candidate
+ * path, transient resolution race) is silently swallowed because
+ * mountServerPackages will re-attempt with full error surfacing; the preload
+ * only warms the cache, never gates boot.
+ */
+
+// Why: Speculatively import every server_package's mount module so …
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 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";
@@ -31,19 +48,6 @@ function mountCandidates(pkg: string): string[] {
 	return [`${pkg}/mount.ts`, `${pkg}/boot/mount.ts`, pkg];
 }
 
-/**
- * Speculatively import every server_package's mount module so Bun compiles
- * the module graphs into its cache NOW, overlapping the (CPU-bound)
- * compilation with whatever I/O the caller runs next. When mountServerPackages
- * later imports the same paths they hit the cache (instant).
- *
- * Same pattern as create-boot-pipeline's speculative preloads — the
- * cross-internet DB I/O in the gate chain (~3.4s) is dead time the compiler
- * can use. Best-effort + non-fatal: a failed import here (wrong candidate
- * path, transient resolution race) is silently swallowed because
- * mountServerPackages will re-attempt with full error surfacing; the preload
- * only warms the cache, never gates boot.
- */
 export async function preloadServerPackages(packages: string[]): Promise<void> {
 	await Promise.allSettled(
 		packages.flatMap((pkg) =>
@@ -70,8 +74,6 @@ export async function mountServerPackages(
 		return mountRegistry;
 	}
 
-
-
 	for (const pkg of serverPackages) {
 		try {
 			let mod: {

package/src/pg-boss-mount.ts

@@ -23,7 +23,6 @@ import { pgBossHandlerRegistry } from "./pg-boss-handler-registry.ts";
 
 // Bundled pg-boss handlers self-register on import (package-subscriber shape).
 // External handler packages register via their own boot hook / subscriber import.
-import "./handlers/prune-stale-data.ts";
 import "./handlers/projects-digest.ts";
 import "./handlers/sweep-event-log.ts";
 // `sweep-host-cache` is Rust-native: loga (the job's service_slug) registers it
@@ -36,7 +35,6 @@ import "./handlers/upstream-issue-sync.ts";
 import "./handlers/scala-tools-currency-watch.ts";
 import "./handlers/singleton-tools-currency-watch.ts";
 import "./handlers/registry-stale-inactive-sweep.ts";
-import "./handlers/pane-outbox-drain.ts";
 import "./handlers/platform-fault-escalation.ts";
 
 /**
@@ -298,16 +296,11 @@ export async function mountPgBoss(
 		}
 	}
 
-	// Reconcile orphaned cron schedules: unschedule any pg-boss schedule that no
-	// longer corresponds to an ACTIVE registry row. Deactivating/deleting a
-	// scheduled_job (or sync_job_handler) previously left its cron lingering in
-	// pgboss.schedule, firing indefinitely — 2 stale web-extractor schedules
-	// found 2026-07-27, still scraping every 3/15min months after the job was meant
-	// to be one-off. Deactivation must actually stop the cron. A schedule is
-	// "backed" iff ANY active registry row's slug OR queue_name equals its name —
-	// this covers scheduled_job AND sync_job_handler (and any future
-	// schedule-owning type) without hardcoding the type list, so live sync jobs
-	// (zoho_assist_sync, trackabi, …) are never touched. Runs on every pg-boss
+	// Reconcile orphaned cron schedules: unschedule any pg-boss schedule that no longer corresponds to an ACTIVE registry row. Deactivating/deleting a
+	// scheduled_job (or sync_job_handler) previously left its cron lingering in pgboss.schedule, firing indefinitely — 2 stale web-extractor schedules
+	// found 2026-07-27, still scraping every 3/15min months after the job was meant to be one-off. Deactivation must actually stop the cron. A schedule is
+	// "backed" iff ANY active registry row's slug OR queue_name equals its name — this covers scheduled_job AND sync_job_handler (and any future
+	// schedule-owning type) without hardcoding the type list, so live sync jobs (zoho_assist_sync, trackabi, …) are never touched. Runs on every pg-boss
 	// mount and reconciles GLOBALLY: an orphan is removed regardless of which
 	// service created it, since a cron with no active backing row is drift by
 	// definition. A service with zero active scheduled jobs early-returns above

package/src/proposal-gate.ts

@@ -18,6 +18,7 @@ import type { AccessConfig, ContentGateConfig } from "./content-gate/config-type
 import { signAccessToken, verifyAccessToken } from "./content-gate/token.ts";
 import { resolveProposalAuthorizedEmails } from "./proposal-authorized-emails.ts";
 import { propTtlMs } from "./gate-ttls.ts";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
 
@@ -49,15 +50,19 @@ const ProposalGateSettingsSchema = v.object({
 });
 
 async function loadProposalGateSettings(): Promise<ProposalGateSettings> {
+	let settingsFailed = false;
 	try {
 		return await loadRegistryConfig(
 			"config",
 			"content-gate-proposal",
 			ProposalGateSettingsSchema,
 		);
-	} catch {
-		return PROPOSAL_GATE_DEFAULTS;
+	} catch (error) {
+		getAppLogger().warn("[proposal-gate] settings read failed — defaults", error);
+		settingsFailed = true;
 	}
+	if (settingsFailed) return PROPOSAL_GATE_DEFAULTS;
+	return PROPOSAL_GATE_DEFAULTS;
 }
 
 const PROP_COOKIE = "prop_token";

package/src/read-html-template.test.ts

@@ -11,8 +11,8 @@
  * hydration. These tests pin that a manifest change re-substitutes the HTML.
  */
 
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { readHtmlTemplate } from "./read-html-template.ts";
@@ -20,28 +20,25 @@ import { readHtmlTemplate } from "./read-html-template.ts";
 let dir: string;
 let origCwd: string;
 
-function writeManifest(hydrate: string, styles: string): void {
-	writeFileSync(
-		join(dir, "dist", "client", "asset-manifest.json"),
-		`${JSON.stringify({ stylesPath: styles, hydratePath: hydrate }, null, 2)}\n`,
-	);
+async function writeManifest(hydrate: string, styles: string): Promise<void> {
+	await Bun.file(join(dir, "dist", "client", "asset-manifest.json")).write(`${JSON.stringify({ stylesPath: styles, hydratePath: hydrate }, null, 2)}\n`);
 }
 
-beforeEach(() => {
+beforeEach(async () => {
 	origCwd = process.cwd();
-	dir = mkdtempSync(join(tmpdir(), "read-html-template-"));
-	mkdirSync(join(dir, "dist", "client"), { recursive: true });
+	dir = await mkdtemp(join(tmpdir(), "read-html-template-"));
+	await mkdir(join(dir, "dist", "client"), { recursive: true });
 	process.chdir(dir);
 });
 
-afterEach(() => {
+afterEach(async () => {
 	process.chdir(origCwd);
-	rmSync(dir, { recursive: true, force: true });
+	await rm(dir, { recursive: true, force: true });
 });
 
 describe("readHtmlTemplate manifest-keyed cache", () => {
 	test("renders the shared Puck document without a per-service HTML file", async () => {
-		writeManifest("/assets/hydrate-aaa.js", "/assets/styles-aaa.css");
+		await writeManifest("/assets/hydrate-aaa.js", "/assets/styles-aaa.css");
 		const html = await readHtmlTemplate();
 		expect(html).toContain('<div id="__page"><!--ssr-outlet--></div>');
 		expect(html).toContain("<!--head-outlet-->");
@@ -50,21 +47,21 @@ describe("readHtmlTemplate manifest-keyed cache", () => {
 	});
 
 	test("substitutes the current manifest hashes", async () => {
-		writeManifest("/assets/hydrate-aaa.js", "/assets/styles-aaa.css");
+		await writeManifest("/assets/hydrate-aaa.js", "/assets/styles-aaa.css");
 		const html = await readHtmlTemplate();
 		expect(html).toContain("/assets/hydrate-aaa.js");
 		expect(html).toContain("/assets/styles-aaa.css");
 	});
 
 	test("re-substitutes after a post-boot manifest change (the 404 regression)", async () => {
-		writeManifest("/assets/hydrate-old.js", "/assets/styles-old.css");
+		await writeManifest("/assets/hydrate-old.js", "/assets/styles-old.css");
 		const first = await readHtmlTemplate();
 		expect(first).toContain("/assets/hydrate-old.js");
 
 		// Simulate build-client-assets rebuilding: new manifest, old bundle gone.
 		// mtime must advance for the stat-keyed cache to invalidate.
 		await Bun.sleep(10);
-		writeManifest("/assets/hydrate-new.js", "/assets/styles-new.css");
+		await writeManifest("/assets/hydrate-new.js", "/assets/styles-new.css");
 
 		const second = await readHtmlTemplate();
 		expect(second).toContain("/assets/hydrate-new.js");

package/src/read-html-template.ts

@@ -101,7 +101,8 @@ async function loadManifest(): Promise<AssetManifest> {
 			if (parsed.stylesPath && parsed.hydratePath) {
 				return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
 			}
-		} catch {}
+		} catch (error) {}
+			getAppLogger().warn("asset manifest unreadable — falling back to default template wiring", error);
 	}
 	return FALLBACK;
 }

package/src/readiness-gate.ts

@@ -11,6 +11,7 @@
  * the normal handler rather than producing a hard 500.
  */
 
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Context, Next } from "hono";
 
 let _ready = false;
@@ -33,7 +34,7 @@ export async function readinessGate(c: Context, next: Next): Promise<Response |
 		// handler — but the failure must be OBSERVABLE, not silent. Practically
 		// unreachable (the body is pure reads of module flags + c.req.path); the
 		// log surfaces a regression if it ever fires.
-		console.error("[readiness-gate] gate threw — failing open to handler", err);
+		getAppLogger().error("[readiness-gate] gate threw — failing open to handler", { error: String(err) });
 		return next();
 	}
 }

package/src/register-crash-handlers.ts

@@ -8,6 +8,8 @@
  * identification. Per constitution crash-isolation.
  */
 
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
 export function registerCrashHandlers(opts: { serviceSlug: string }): {
 	unhandledRejection: boolean;
 	uncaughtException: boolean;
@@ -17,20 +19,14 @@ export function registerCrashHandlers(opts: { serviceSlug: string }): {
 
 	if (process.listenerCount("unhandledRejection") === 0) {
 		process.on("unhandledRejection", (reason) => {
-			console.error(
-				`[scala-install:${opts.serviceSlug}] unhandledRejection:`,
-				reason,
-			);
+			getAppLogger().error(`[scala-install:${opts.serviceSlug}] unhandledRejection:`, { error: String(reason) });
 		});
 		unhandledRejection = true;
 	}
 
 	if (process.listenerCount("uncaughtException") === 0) {
 		process.on("uncaughtException", (err) => {
-			console.error(
-				`[scala-install:${opts.serviceSlug}] uncaughtException:`,
-				err,
-			);
+			getAppLogger().error(`[scala-install:${opts.serviceSlug}] uncaughtException:`, { error: String(err) });
 		});
 		uncaughtException = true;
 	}

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

@@ -9,6 +9,21 @@
  * any page route handler fires.
  */
 
+		// REFUSE, DO NOT SKIP. `existsSync(routerPath)` being false used to fall straight through with appRouter=null and still register a client + log
+		// success. That client carries only the three platform routers below and NO CRUD models, which is indistinguishable from a healthy one until a
+		// page asks it for a model — at which point resolve-from-loader-config throws MissingLoaderModelCapabilityError, far from the actual fault.
+		//
+		// Measured 2026-08-20: scala-quiz and scala-forms served 500s on every data-backed page while /health returned 200 and this line logged "ORPC
+		// serverClient registered". The build had produced no generated router (its railpack.json ran registry codegen against an unreachable
+		// *.railway.internal host), and nothing anywhere said so.
+		//
+		// A service whose service_schema DECLARES models and has no generated router is not degraded, it is non-functional — so this fails the boot
+		// rather than reporting a state it has not verified (`a-component-may-not-report-a-state-it-has-not-verified`). A service
+		// that declares no models (daemon/portal shells owning no DB schema) still passes through cleanly.
+
+// Why: REFUSE, DO NOT SKIP. `existsSync(routerPath)` being false us…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 
@@ -52,25 +67,6 @@ export async function registerPageServerClient(
 				);
 			}
 		}
-		// REFUSE, DO NOT SKIP. `existsSync(routerPath)` being false used to fall
-		// straight through with appRouter=null and still register a client + log
-		// success. That client carries only the three platform routers below and
-		// NO CRUD models, which is indistinguishable from a healthy one until a
-		// page asks it for a model — at which point resolve-from-loader-config
-		// throws MissingLoaderModelCapabilityError, far from the actual fault.
-		//
-		// Measured 2026-08-20: scala-quiz and scala-forms served 500s on every
-		// data-backed page while /health returned 200 and this line logged "ORPC
-		// serverClient registered". The build had produced no generated router
-		// (its railpack.json ran registry codegen against an unreachable
-		// *.railway.internal host), and nothing anywhere said so.
-		//
-		// A service whose service_schema DECLARES models and has no generated
-		// router is not degraded, it is non-functional — so this fails the boot
-		// rather than reporting a state it has not verified
-		// (`a-component-may-not-report-a-state-it-has-not-verified`). A service
-		// that declares no models (daemon/portal shells owning no DB schema)
-		// still passes through cleanly.
 		const declaredModels = await (async () => {
 			try {
 				const { loadRegistryConfig: loadCfg } = await import(

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

@@ -7,6 +7,22 @@
  * panel renders the real conversation on first paint. Extracted from
  * register-registry-page-route.ts (single-purpose-file split).
  */
+/**
+ * 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.
+ */
+
+// Why: SSR-prefetch the signed-in user's AI-chat conversation so a …
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { getServerClient } from "../page-server-orpc/server-client.ts";
 
 /**
@@ -33,18 +49,6 @@ function findWebsiteId(root: unknown): string | undefined {
 	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,