@teamscala/service-boot 0.23.383 → 0.23.384

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.383",
+  "version": "0.23.384",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -922,14 +922,6 @@
       "types": "./src/server-error-page.d.ts",
       "default": "./src/server-error-page.ts"
     },
-    "./start-scheduled-jobs": {
-      "types": "./src/start-scheduled-jobs.d.ts",
-      "default": "./src/start-scheduled-jobs.ts"
-    },
-    "./start-scheduled-jobs.ts": {
-      "types": "./src/start-scheduled-jobs.d.ts",
-      "default": "./src/start-scheduled-jobs.ts"
-    },
     "./two-phase-boot": {
       "types": "./src/two-phase-boot.d.ts",
       "default": "./src/two-phase-boot.ts"

package/src/mount-server-packages.ts

@@ -147,7 +147,7 @@ export async function mountServerPackages(
 
 	log.info(
 		`[scala-install:${serviceSlug}] Registered ${mountRegistry.handlers.size} handler(s), ` +
-			`${mountRegistry.wsRoutes.size} ws route(s), ${mountRegistry.scheduledJobs.size} scheduled job(s), ` +
+			`${mountRegistry.wsRoutes.size} ws route(s), ` +
 			`${mountRegistry.bootHooks.size} boot hook(s)`,
 	);
 

package/src/page-server-orpc/server-client.test.ts

@@ -0,0 +1,68 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The empty-router substitute that hid a total outage.
+ *
+ * MEASURED 2026-08-20: scala-quiz and scala-forms served 500s on every
+ * data-backed page for hours. /health returned 200 and boot logged "ORPC
+ * serverClient registered", because an unregistered read was answered with
+ * `createRouterClient({}, …)` — a client that looks registered and carries no
+ * models. The fault only surfaced later and elsewhere, as
+ * MissingLoaderModelCapabilityError during page render.
+ *
+ * These pin the contract: a missing client is an error at the point of the
+ * fault, never a fabricated stand-in.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+	getServerClient,
+	isServerClientRegistered,
+	setServerClient,
+} from "./server-client.ts";
+
+afterEach(() => {
+	setServerClient(null as never);
+});
+
+describe("page-server server client", () => {
+	test("throws rather than substituting an empty router when unregistered", () => {
+		setServerClient(null as never);
+		expect(() => getServerClient()).toThrow(
+			/no ORPC server client registered/,
+		);
+	});
+
+	test("the failure names the boot step responsible", () => {
+		setServerClient(null as never);
+		expect(() => getServerClient()).toThrow(/registerPageServerClient/);
+	});
+
+	test("never returns a model-less object that reads as healthy", () => {
+		// The whole defect in one assertion: the old fallback returned a truthy
+		// client, so callers could not tell registration had never happened.
+		setServerClient(null as never);
+		let returned: unknown = "sentinel";
+		try {
+			returned = getServerClient();
+		} catch {
+			returned = "threw";
+		}
+		expect(returned).toBe("threw");
+	});
+
+	test("returns the registered client once boot sets one", () => {
+		const client = { assessments: { findFirst: async () => null } };
+		setServerClient(client as never);
+		expect(getServerClient()).toBe(client as never);
+	});
+
+	test("isServerClientRegistered tracks registration state", () => {
+		setServerClient(null as never);
+		expect(isServerClientRegistered()).toBe(false);
+		setServerClient({ x: 1 } as never);
+		expect(isServerClientRegistered()).toBe(true);
+	});
+});

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

@@ -10,20 +10,46 @@
  * at boot, after createRouterClient(appRouter, { context: { prisma } }).
  * Then page-server's createPageHandler reads `getServerClient()` per request
  * — no HTTP loopback, just a typed function call.
+ *
+ * NO EMPTY-ROUTER SUBSTITUTE. This used to answer an unregistered read by
+ * fabricating `createRouterClient({}, …)` — a client with no models on it. That
+ * turned "boot never registered a client" into "every model lookup returns
+ * undefined", which surfaces far away as MissingLoaderModelCapabilityError on
+ * page render rather than as a boot failure. Measured 2026-08-20: quiz and forms
+ * served 500s on every data-backed page for hours while /health returned 200 and
+ * boot logged "ORPC serverClient registered", because the empty router is
+ * indistinguishable from a real one until something asks it for a model
+ * (`a-component-may-not-report-a-state-it-has-not-verified`).
+ *
+ * A missing client is now a thrown error naming the boot step that should have
+ * set it, so the failure is reported by the component that has the fault.
  */
 
-import { createRouterClient, os } from "@orpc/server";
-
-const emptyRouter = {};
+import { createRouterClient } from "@orpc/server";
 
 let serverClient: ReturnType<typeof createRouterClient> | null = null;
 
+/**
+ * The registered server client. Throws if boot never registered one — never
+ * substitutes an empty router, see the file header.
+ */
 export function getServerClient(): ReturnType<typeof createRouterClient> {
-	if (serverClient) return serverClient;
-	serverClient = createRouterClient(emptyRouter, { context: {} });
+	if (!serverClient) {
+		throw new Error(
+			"[page-server] no ORPC server client registered — registerPageServerClient() " +
+				"did not run or failed during boot. A page-server read cannot be served " +
+				"without it; the previous empty-router fallback hid this as a per-model " +
+				"'does not expose findFirst' error at render time.",
+		);
+	}
 	return serverClient;
 }
 
+/** True once boot has registered a client. For callers that must degrade rather than throw. */
+export function isServerClientRegistered(): boolean {
+	return serverClient !== null;
+}
+
 export function setServerClient(
 	client: ReturnType<typeof createRouterClient>,
 ): void {

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

@@ -52,6 +52,60 @@ 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(
+					"@teamscala/db/registry/load-config"
+				);
+				// serviceSlug is runtime-dynamic (the service being booted), so it
+				// cannot satisfy the generated ServiceSchemaKey union statically.
+				const row = (await loadCfg(
+					"service_schema",
+					serviceSlug as never,
+					undefined as never,
+				)) as
+					| { models?: string[] }
+					| null;
+				return Array.isArray(row?.models) ? row.models : [];
+			} catch {
+				// No service_schema row, or it could not be read: fall back to
+				// "declares nothing", so a read failure cannot manufacture a boot
+				// refusal on a service that never needed a router.
+				return [] as string[];
+			}
+		})();
+		if (declaredModels.length > 0 && !appRouter) {
+			throw new Error(
+				`[scala-install:${serviceSlug}] service_schema declares ${declaredModels.length} ` +
+					`model(s) (${declaredModels.slice(0, 5).join(", ")}${declaredModels.length > 5 ? ", …" : ""}) ` +
+					`but no generated ORPC router is present at ${routerPath}. Every data-backed page ` +
+					`would 500 with MissingLoaderModelCapabilityError while /health reported 200. ` +
+					`This is a BUILD fault: deploy-build did not emit prisma/generated/orpc. Check that ` +
+					`the service's railpack.json runs deploy-build with DATABASE_URL_FROM_OUTSIDE ` +
+					`(the builder cannot resolve *.railway.internal) and that its codegen_output row ` +
+					`for railpack-json carries the composite input the transform declares.`,
+			);
+		}
+
 		const { puckPagesRouter } = await import(
 			"@teamscala/service-boot/page-server-orpc/puck-pages-router"
 		);
@@ -94,12 +148,19 @@ export async function registerPageServerClient(
 			} as never,
 		);
 		mod.setServerClient(client);
+		// State the model count. "registered" alone was true in the outage and told
+		// nobody anything; a zero here is now visible in the boot log.
 		log.info(
-			`[scala-install:${serviceSlug}] ORPC serverClient registered (system:super-admin)`,
+			`[scala-install:${serviceSlug}] ORPC serverClient registered (system:super-admin) — ` +
+				`${Object.keys(composed).length} router(s), ${declaredModels.length} declared model(s)`,
 		);
 	} catch (err) {
-		log.warn(
-			`[scala-install:${serviceSlug}] Failed to load appRouter for serverClient: ${err instanceof Error ? err.message : err}`,
+		// RETHROW. Swallowing this into a warn is what let a service boot, pass its
+		// healthcheck and serve 500s on every page. The boot must fail so the
+		// supervisor and the deploy healthcheck can see it.
+		log.error(
+			`[scala-install:${serviceSlug}] serverClient registration FAILED — data-backed pages cannot render: ${err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err)}`,
 		);
+		throw err;
 	}
 }

package/src/resolve-from-loader-config.test.ts

@@ -16,6 +16,7 @@ import {
 } from "./resolve-from-loader-config";
 import {
 	getServerClient,
+	isServerClientRegistered,
 	setServerClient,
 } from "./page-server-orpc/server-client";
 
@@ -52,7 +53,7 @@ describe("interpolateMeta (resolver_input ref contract)", () => {
 
 describe("resource-loader model capability", () => {
 	test("an optional source still refuses a model absent from the generated client", async () => {
-		const original = getServerClient();
+		const original = isServerClientRegistered() ? getServerClient() : null;
 		setServerClient({} as never);
 		try {
 			await expect(
@@ -73,12 +74,12 @@ describe("resource-loader model capability", () => {
 				'requires model "builda_pages", but the generated server client does not expose findFirst',
 			);
 		} finally {
-			setServerClient(original);
+			setServerClient(original as never);
 		}
 	});
 
 	test("an optional source may resolve an absent row when the model capability exists", async () => {
-		const original = getServerClient();
+		const original = isServerClientRegistered() ? getServerClient() : null;
 		setServerClient({
 			builda_pages: { findFirst: async () => null },
 		} as never);
@@ -99,7 +100,7 @@ describe("resource-loader model capability", () => {
 				),
 			).resolves.toEqual({ body: null });
 		} finally {
-			setServerClient(original);
+			setServerClient(original as never);
 		}
 	});
 });

package/src/two-phase-boot.test.ts

@@ -4,13 +4,13 @@
  * @edit edit directly
  *
  * Phase-2 step isolation: a client-asset build failure must not prevent
- * scheduled jobs and pg-boss from mounting.
+ * pg-boss from mounting.
  *
  * Asserted against the SOURCE rather than by booting a service, because the
  * behaviour is an ordering/error-handling property of buildFullApp and booting
  * it here would need a database, a registry, a Vite build and a live pg-boss.
  * The property is structural: buildClientAssets must be inside a try/catch that
- * appears BEFORE the startScheduledJobs and mountPgBoss calls. That is exactly
+ * appears BEFORE the mountPgBoss call. That is exactly
  * what regressed, and a source assertion fails the moment someone re-awaits it
  * unguarded — which is the regression this locks.
  */
@@ -55,8 +55,8 @@ describe("phase-2 step isolation", () => {
 
 	/*
 	 * THE LOAD-BEARING ASSERTION. A `catch` must appear BETWEEN the build call and
-	 * the startScheduledJobs call. That is what makes this test fail if the guard
-	 * is removed: unwrap the await and there is no catch in that span, so the
+	 * the mountPgBoss call. That is what makes this test fail if the guard is
+	 * removed: unwrap the await and there is no catch in that span, so the
 	 * expectation cannot be satisfied by some unrelated try/catch elsewhere in the
 	 * function. Ordering alone would NOT catch the regression — the original buggy
 	 * code also had jobs after the build; it just had no catch in between.
@@ -64,13 +64,11 @@ describe("phase-2 step isolation", () => {
 	test("a catch sits between the build and the jobs, so a throw cannot skip them", () => {
 		const body = buildFullAppBody();
 		const build = body.indexOf("buildClientAssets(serviceSlug)");
-		const jobs = body.indexOf("startScheduledJobs(");
 		const boss = body.indexOf("mountPgBoss(");
 		expect(build).toBeGreaterThan(-1);
-		expect(jobs).toBeGreaterThan(build);
 		expect(boss).toBeGreaterThan(build);
 
-		const between = body.slice(build, jobs);
+		const between = body.slice(build, boss);
 		expect(between).toContain("catch");
 	});
 

package/src/two-phase-boot.ts

@@ -48,7 +48,6 @@ import {
 	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";
@@ -529,10 +528,10 @@ export async function buildFullApp(
 	//
 	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
 	// This was awaited unguarded, so a throw here aborted buildFullApp before
-	// startScheduledJobs and mountPgBoss ran, and the caller's catch logged
+	// 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 scheduled job and
-	// every pg-boss handler on the service.
+	// 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
@@ -541,9 +540,9 @@ export async function buildFullApp(
 	// 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: jobs and pg-boss
-	// need the registry and the DB, not a bundle. Ordering them behind a Vite
-	// build was incidental, so the coupling was never intended.
+	// 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.
 	try {
 		await buildClientAssets(serviceSlug);
 		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
@@ -557,10 +556,6 @@ export async function buildFullApp(
 		);
 	}
 
-	// Scheduled jobs
-	startScheduledJobs(config, mountRegistry, serviceSlug);
-	log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: scheduledJobs DONE`);
-
 	// pg-boss (mount for UI services - wasn't mounted in minimal app)
 	const { jobs: pgBossJobs } = await mountPgBoss({
 		databaseUrl: minimalResult.databaseUrl,

package/src/start-scheduled-jobs.ts

@@ -1,84 +0,0 @@
-/**
- * @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.`,
-			);
-		}
-	}
-}