@teamscala/service-boot 0.23.385 → 0.23.386

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.385",
+  "version": "0.23.386",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

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

@@ -19,7 +19,9 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import {
 	getServerClient,
+	getServerClientCapabilityFault,
 	isServerClientRegistered,
+	recordServerClientCapability,
 	setServerClient,
 } from "./server-client.ts";
 
@@ -66,3 +68,45 @@ describe("page-server server client", () => {
 		expect(isServerClientRegistered()).toBe(true);
 	});
 });
+
+describe("declared-vs-present capability probe (/health)", () => {
+	test("no fault when every declared model is servable", () => {
+		setServerClient({
+			assessments: { findFirst: async () => null },
+			assessment_responses: { findFirst: async () => null },
+		} as never);
+		recordServerClientCapability(["assessments", "assessment_responses"]);
+		expect(getServerClientCapabilityFault()).toBeNull();
+	});
+
+	test("names the models the client cannot serve", () => {
+		// THE OUTAGE, AS A HEALTH ANSWER. A client was registered and carried only
+		// the platform routers, so every process-existence signal was green while
+		// every data-backed page 500d. /health must be able to say this.
+		setServerClient({ puckPages: {}, userPreferences: {} } as never);
+		recordServerClientCapability(["assessments", "assessment_responses"]);
+		const fault = getServerClientCapabilityFault();
+		expect(fault).toContain("assessments");
+		expect(fault).toContain("assessment_responses");
+	});
+
+	test("a service declaring no models is never faulted", () => {
+		// Daemon/portal shells own no DB schema and are healthy with an empty client.
+		setServerClient({ puckPages: {} } as never);
+		recordServerClientCapability([]);
+		expect(getServerClientCapabilityFault()).toBeNull();
+	});
+
+	test("an unregistered client is itself the fault", () => {
+		setServerClient(null as never);
+		recordServerClientCapability(["assessments"]);
+		expect(getServerClientCapabilityFault()).toContain("no ORPC server client registered");
+	});
+
+	test("a model present without findFirst still counts as missing", () => {
+		// The generated router shape is what matters, not mere key presence.
+		setServerClient({ assessments: {} } as never);
+		recordServerClientCapability(["assessments"]);
+		expect(getServerClientCapabilityFault()).toContain("assessments");
+	});
+});

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

@@ -55,3 +55,36 @@ export function setServerClient(
 ): void {
 	serverClient = client;
 }
+
+/**
+ * Declared-vs-present capability, recorded once at boot by
+ * registerPageServerClient and read by /health.
+ *
+ * The outage this exists for: a client WAS registered, so every
+ * process-existence signal was green, and it carried no CRUD models. Liveness
+ * must be a capability probe, never a registration check
+ * (`liveness-by-capability-not-process-existence`).
+ */
+let capabilityFault: string | null = null;
+
+/**
+ * Record whether the registered client can actually serve the models the
+ * service declares. Property lookups only — no I/O — so /health stays cheap.
+ */
+export function recordServerClientCapability(declaredModels: readonly string[]): void {
+	if (!serverClient) {
+		capabilityFault = "no ORPC server client registered";
+		return;
+	}
+	const client = serverClient as unknown as Record<string, { findFirst?: unknown } | undefined>;
+	const missing = declaredModels.filter((m) => typeof client[m]?.findFirst !== "function");
+	capabilityFault =
+		missing.length === 0
+			? null
+			: `generated client exposes no findFirst for ${missing.length} declared model(s): ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", …" : ""}`;
+}
+
+/** The capability fault, or null when the service can serve its declared models. */
+export function getServerClientCapabilityFault(): string | null {
+	return capabilityFault;
+}

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

@@ -148,6 +148,9 @@ export async function registerPageServerClient(
 			} as never,
 		);
 		mod.setServerClient(client);
+		// Record declared-vs-present capability for /health. Property lookups only.
+		(mod as unknown as { recordServerClientCapability?: (m: readonly string[]) => void })
+			.recordServerClientCapability?.(declaredModels);
 		// 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(