@teamscala/service-boot 0.23.515 → 0.23.516

package/package.json

@@ -1187,5 +1187,5 @@
   "repository": "https://github.com/teamgbg/service-boot",
   "sideEffects": false,
   "type": "module",
-  "version": "0.23.515"
+  "version": "0.23.516"
 }

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

@@ -0,0 +1,185 @@
+// @system ui-service-boot
+// @status handwritten
+// @edit edit directly
+//
+// register-page-server-client.test.ts — the declaredModels lookup must never
+// quietly report "declares nothing".
+//
+// The regression this exists for (measured scala-sign 2026-09-24/25): the boot
+// looked up service_schema with `undefined as never`, so loadRegistryConfig's
+// `v.parse(undefined, raw)` threw a TypeError on EVERY service, the bare
+// `catch {}` swallowed it into `declaredModels = []`, and the
+// "declares > 0 models + no router → refuse the boot" check below never fired.
+// A service declaring 18 models logged "0 declared model(s)", registered a
+// router-less server client as healthy, and served 500 on every page while
+// /health answered 200.
+//
+// Three assertions, each the operator's demand ("the catch must tell 'no
+// service_schema row' apart from 'the read failed'. A read error must never
+// quietly become 'no models'. Test both"):
+//   1. a service that DECLARES models with no generated router → REFUSES the
+//      boot (proves the refusal actually fires now — it did not before);
+//   2. a service with NO service_schema row → passes through clean (legitimate
+//      daemon/portal shell owns no DB models);
+//   3. a service_schema READ that FAILS → REFUSES the boot naming the error
+//      (a read error is never treated as "declares nothing").
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const originalCwd = process.cwd();
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+	process.chdir(originalCwd);
+	for (const directory of tempDirs.splice(0)) {
+		await rm(directory, { recursive: true, force: true });
+	}
+});
+
+// The registry read is scenario-driven: ONE load-config mock serves all three
+// tests, and each test flips the mode before calling the function. The mock
+// function is re-invoked on every call (the target imports it dynamically
+// inside registerPageServerClient), so switching the mode takes effect.
+let registryMode:
+	| { kind: "row"; models: string[] }
+	| { kind: "missing" }
+	| { kind: "missing-thrown" }
+	| { kind: "read-failed"; message: string } = { kind: "missing" };
+
+// The class identity the catch's `instanceof` compares against. The target
+// imports RegistryConfigMissingError from @teamscala/db/registry/errors, so the
+// SAME mocked class must back both the throw path and the instanceof check.
+class MockRegistryConfigMissingError extends Error {
+	readonly type: string;
+	readonly slug: string;
+	constructor(type: string, slug: string) {
+		super(`[registry] Config entry "${slug}" of type "${type}" not found`);
+		this.name = "RegistryConfigMissingError";
+		this.type = type;
+		this.slug = slug;
+	}
+}
+
+mock.module("@teamscala/db/registry/load-config", () => ({
+	loadOptionalRegistryConfig: async () => {
+		if (registryMode.kind === "missing") return null;
+		if (registryMode.kind === "missing-thrown") {
+			throw new MockRegistryConfigMissingError("service_schema", "scala-sign");
+		}
+		if (registryMode.kind === "row") return { models: registryMode.models };
+		throw new Error(registryMode.message);
+	},
+	loadRegistryConfig: async () => ({ platformOrganisationId: "org-platform" }),
+}));
+
+mock.module("@teamscala/db/registry/errors", () => ({
+	RegistryConfigMissingError: MockRegistryConfigMissingError,
+}));
+
+mock.module("@teamscala/db-validation/registry-schemas/service-schema", () => ({
+	ServiceSchemaConfigSchema: {},
+}));
+
+mock.module("@teamscala/db-validation/registry-schemas/platform-identity", () => ({
+	PlatformIdentitySchema: {},
+}));
+
+mock.module("@teamscala/logger/app-loggers", () => ({
+	getAppLogger: () => ({
+		info: (..._args: unknown[]) => {},
+		warn: (..._args: unknown[]) => {},
+		error: (..._args: unknown[]) => {},
+	}),
+}));
+
+mock.module("@orpc/server", () => ({
+	createRouterClient: () => ({}),
+}));
+
+mock.module("@teamscala/db/prisma-registry", () => ({
+	getPrisma: () => ({}),
+}));
+
+// The page-server server-client is imported dynamically via a string-cast
+// specifier inside the function; mock the exact specifier so setServerClient
+// is a recording no-op and the real runtime never loads.
+const setServerClientCalls: number[] = [];
+mock.module("@teamscala/service-boot/page-server-orpc/server-client", () => ({
+	setServerClient: () => {
+		setServerClientCalls.push(1);
+	},
+}));
+
+const { registerPageServerClient } = await import(
+	"./register-page-server-client.ts"
+);
+
+/** Make an empty service dir with NO generated router anywhere, and reset the
+ *  setServerClient recorder so each test's count is its own. */
+async function cwdWithoutRouter(): Promise<string> {
+	setServerClientCalls.length = 0;
+	const dir = await mkdtemp(join(tmpdir(), "register-psc-test-"));
+	tempDirs.push(dir);
+	process.chdir(dir);
+	return dir;
+}
+
+describe("registerPageServerClient — declaredModels lookup never lies", () => {
+	test("refuses the boot when the service DECLARES models but no router exists", async () => {
+		await cwdWithoutRouter();
+		registryMode = {
+			kind: "row",
+			// 18 models — the exact scala-sign row size whose absence from the
+			// boot log was the outage.
+			models: Array.from({ length: 18 }, (_unused, index) => `model_${index}`),
+		};
+
+		await expect(registerPageServerClient("scala-sign")).rejects.toThrow(
+			/service_schema declares 18 model\(s\).*no generated ORPC router is present/s,
+		);
+		expect(setServerClientCalls.length).toBe(0);
+	});
+
+	test("passes through clean when there is NO service_schema row", async () => {
+		await cwdWithoutRouter();
+		// loadOptionalRegistryConfig returns null — the legitimately-declares-
+		// nothing case (daemon/portal shell). With no models declared there is no
+		// router required, so the boot must NOT refuse.
+		registryMode = { kind: "missing" };
+
+		await expect(registerPageServerClient("some-daemon-shell")).resolves.toBeUndefined();
+		expect(setServerClientCalls.length).toBeGreaterThan(0);
+	});
+
+	test("refuses the boot when the service_schema READ fails, naming the error", async () => {
+		await cwdWithoutRouter();
+		// A read error (NOT a missing row) must fail the boot, never degrade to
+		// "declares nothing" — otherwise a data-backed service boots "0 models"
+		// and 500s on every page.
+		registryMode = { kind: "read-failed", message: "connection refused: db down" };
+
+		await expect(registerPageServerClient("scala-sign")).rejects.toThrow(
+			/service_schema read FAILED for "scala-sign"/,
+		);
+		await expect(registerPageServerClient("scala-sign")).rejects.toThrow(
+			/connection refused: db down/,
+		);
+		expect(setServerClientCalls.length).toBe(0);
+	});
+
+	test("treats a thrown RegistryConfigMissingError as declares-nothing, not failure", async () => {
+		await cwdWithoutRouter();
+		// The read path throws RegistryConfigMissingError (a genuinely-absent row,
+		// the same signal as a null return, just a different code path): the catch
+		// must classify it as "declares nothing" via the instanceof check and boot
+		// CLEAN — this is exactly the branch that must NOT fail the boot. Contrast
+		// the read-failed test above, where an unrelated error DOES fail the boot.
+		registryMode = { kind: "missing-thrown" };
+
+		await expect(registerPageServerClient("scala-sign")).resolves.toBeUndefined();
+		expect(setServerClientCalls.length).toBeGreaterThan(0);
+	});
+});

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

@@ -65,37 +65,58 @@ export async function registerPageServerClient(
 				);
 			}
 		}
-		const declaredModels = await (async () => {
+		const declaredModels = await (async (): Promise<string[]> => {
+			const capSlug = toCapabilitySlug(serviceSlug);
+			// LOOK IT UP BY CAPABILITY, NOT BY DEPLOYABLE NAME. A service_schema
+			// row describes the APPLICATION's data surface, so there is ONE row
+			// for both lanes; the dev lane arrives here as
+			// `scala-projects-bun-dev`. Both sides normalize through
+			// toCapabilitySlug, so the join is tier-agnostic by construction.
+			// See ./capability-slug.ts.
+			//
+			// READ WITH THE REAL SCHEMA, NOT `undefined`. The previous call passed
+			// `undefined as never`, so v.parse(undefined, raw) threw a TypeError
+			// (schema is not a schema) on EVERY service, the bare catch below turned
+			// that into "declares nothing", and the refusal at the bottom NEVER
+			// fired — a service declaring 18 models booted "0 declared model(s)"
+			// and served 500s. (measured scala-sign 2026-09-24/25: row declares 18,
+			// boot logged 0.) loadOptionalRegistryConfig parses against
+			// ServiceSchemaConfigSchema and returns null ONLY for a missing row.
+			//
+			// A MISSING ROW is legitimately "declares nothing" (daemon/portal
+			// shells own no DB models) and passes through clean. A READ FAILURE is
+			// NOT "declares nothing" — it fails the boot naming the error, so the
+			// database can never quietly become "no models" and let a router-less,
+			// data-backed service boot and serve 500s
+			// (`a-component-may-not-report-a-state-it-has-not-verified`).
+			const { loadOptionalRegistryConfig } = await import(
+				"@teamscala/db/registry/load-config"
+			);
+			const { RegistryConfigMissingError } = await import(
+				"@teamscala/db/registry/errors"
+			);
+			const { ServiceSchemaConfigSchema } = await import(
+				"@teamscala/db-validation/registry-schemas/service-schema"
+			);
 			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.
-				//
-				// LOOK IT UP BY CAPABILITY, NOT BY DEPLOYABLE NAME. A service_schema
-				// row describes the APPLICATION's data surface, so there is ONE row
-				// for both lanes; the dev lane arrives here as
-				// `scala-projects-bun-dev` and matched nothing. The catch below then
-				// read "declares nothing" and the refusal fifteen lines down never
-				// fired — so a router-less client registered as healthy and every
-				// data-backed page 500ed with MissingLoaderModelCapabilityError,
-				// which is precisely the outage this refusal exists to prevent
-				// (measured 2026-09-11 on scala-projects-bun-dev: "0 declared
-				// model(s)" against a row declaring 31). See ./capability-slug.ts.
-				const row = (await loadCfg(
+				const row = await loadOptionalRegistryConfig(
 					"service_schema",
-					toCapabilitySlug(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[];
+					capSlug as never,
+					ServiceSchemaConfigSchema,
+				);
+				if (row === null) return [];
+				return Array.isArray(row.models) ? row.models : [];
+			} catch (err) {
+				if (err instanceof RegistryConfigMissingError) return [];
+				throw new Error(
+					`[scala-install:${serviceSlug}] service_schema read FAILED for ` +
+						`"${capSlug}" — this is NOT treated as "declares nothing". A ` +
+						`registry read error must never quietly become an empty model ` +
+						`set, because a data-backed service with no generated ORPC ` +
+						`router would otherwise boot healthy and 500 on every page. ` +
+						`Underlying error: ${err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err)}`,
+					{ cause: err },
+				);
 			}
 		})();
 		if (declaredModels.length > 0 && !appRouter) {
@@ -104,10 +125,10 @@ export async function registerPageServerClient(
 					`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.`,
+					`This is a BUILD fault: the codegen_output emission for the ORPC router ` +
+					`(prisma/generated/orpc/routers/index.ts) is missing from the bundle — check that ` +
+					`the service's codegen_output rows are active and their outputs land in the image. ` +
+					`Rebuild via scala-pack; never patch the image by hand.`,
 			);
 		}