@teamscala/service-boot 0.23.477 → 0.23.479

package/package.json

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

package/src/fn-routers/assessment-research-report-data.test.ts

@@ -14,6 +14,7 @@ import {
 	type ReportAssessmentInput,
 	type StageBand,
 } from "./assessment-report-data.ts";
+import { assessmentResearchFindingsSchema } from "@teamscala/db-validation/generated/assessment-research-findings";
 
 const ANNA_LINKEDIN_RAW = "https://www.linkedin.com/in/annaosherov/";
 const ANNA_KEY = "linkedin.com/in/annaosherov";
@@ -173,7 +174,17 @@ describe("research shaping", () => {
 		).toThrow(/superseded/);
 	});
 
-	test("malformed authored findings throw instead of silently rendering garbage", () => {
+	// The db-validation generated schema is the contract this parse enforces.
+	// While the generated artifact is still the permissive v.record fallback
+	// (the codegen engine that emits the faithful schema embeds
+	// STRUCTURED_JSONB_KEYS at its build and needs an engine rebuild with
+	// @teamscala/codegen >= 2.1.585 — then `scala-tools codegen run --output
+	// db-column-validation --force`, publish db-validation, bump here), this
+	// test activates itself: the skip is a property of the shipped artifact,
+	// not of the expectation.
+	const schemaIsFaithful = !("key" in (assessmentResearchFindingsSchema as object));
+	const enforceTest = schemaIsFaithful ? test : test.skip;
+	enforceTest("malformed authored findings throw instead of silently rendering garbage", () => {
 		expect(() => readResearchFindings({ groups: "not-an-array" })).toThrow();
 	});
 });

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

@@ -13,7 +13,10 @@ 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";
-
+// Captured at module-load time — BEFORE any mock.module() in the test bodies
+// replaces the specifier — so the error-hook test can restore the REAL
+// configured-primitive surface the mount wires the recorder through.
+import * as orpcConfigureReal from "@teamscala/orpc/configure";
 const originalCwd = process.cwd();
 const tempDirs: string[] = [];
 
@@ -85,3 +88,96 @@ describe("mountOrpcRouter generated-artifact seam", () => {
 		expect(seenKeys).not.toContain("getMcpGatewayUrl");
 	});
 });
+
+describe("mountOrpcRouter procedure error hook", () => {
+	test("a throwing procedure through the mounted route records a durable event with the stack", async () => {
+		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 = {};\n");
+		process.chdir(service);
+
+		const { os } = await import("@orpc/server");
+		// The REAL installed orpc surface stays live (configure +
+		// procedure-error-report + the RPCHandler the mount builds) so the
+		// asserted record proves the wiring, not a mock agreeing with itself.
+		// Only the app router source and the event-log write boundary are
+		// replaced. The earlier test in this file partially mocked the
+		// configure specifier; restore the real exports first. getPrisma is
+		// configured because the route reads it per request.
+		mock.module("@teamscala/orpc/configure", () => orpcConfigureReal);
+		const { configure: orpcConfigure } = await import(
+			"@teamscala/orpc/configure"
+		);
+		orpcConfigure({ getPrisma: () => ({}) as never });
+
+		const recordedEvents: Array<{ kind: string; payload: unknown }> = [];
+		mock.module("@teamscala/orpc/app-router", () => ({
+			getAppRouter: async () => ({
+				fn: {
+					test: {
+						boom: os.handler(async () => {
+							throw new ReferenceError("mount-boundary boom");
+						}),
+					},
+				},
+			}),
+		}));
+		mock.module("@teamscala/event-log/record-event", () => ({
+			recordEvent: (input: { kind: string; payload: unknown }) => {
+				recordedEvents.push(input);
+			},
+		}));
+
+		let routeHandler: ((c: unknown) => Promise<Response>) | undefined;
+		const app = {
+			post: (
+				_path: string,
+				...handlers: Array<(c: unknown) => Promise<Response>>
+			) => {
+				routeHandler = handlers.at(-1);
+			},
+		};
+		await mountOrpcRouter(app as never, "scala-mcp");
+		expect(routeHandler).toBeTypeOf("function");
+
+		const response = await routeHandler?.({
+			req: {
+				raw: new Request("http://localhost/api/rpc/fn/test/boom", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({}),
+				}),
+				path: "/api/rpc/fn/test/boom",
+				method: "POST",
+			},
+			notFound: () => new Response(null, { status: 404 }),
+		});
+
+		expect(response?.status).toBe(500);
+		expect(recordedEvents).toHaveLength(1);
+		const { kind, payload } = recordedEvents[0];
+		expect(kind).toBe("orpc.procedure.failed");
+		const record = payload as {
+			procedure: string;
+			errorName: string;
+			message: string;
+			errorId: string;
+			stackHead: string;
+		};
+		expect(record.procedure).toBe("fn.test.boom");
+		expect(record.errorName).toBe("ReferenceError");
+		expect(record.message).toContain("mount-boundary boom");
+		expect(record.errorId).toBeTruthy();
+		const stackLines = record.stackHead.split("\n");
+		expect(stackLines.length).toBeGreaterThanOrEqual(2);
+		expect(stackLines[0]).toContain("ReferenceError");
+	});
+});

package/src/mount-orpc-router.ts

@@ -11,7 +11,7 @@
 
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
-import type { InjectedDb8 } from "@teamscala/db/db8-registry";
+import type { Db8Client } from "@teamscala/db/db8-registry";
 import type { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 
@@ -94,8 +94,28 @@ export async function mountOrpcRouter(
 		const router = await getAppRouter();
 		if (!router || Object.keys(router).length === 0) return null;
 
+		// The mount error hook: every procedure error crossing this boundary is
+		// shaped by buildErrorReport (errorId, class, stack head) and recorded
+		// durably via event-log before ORPC swallows it into a stackless 500.
+		// The recorder is wired HERE because orpc is primitives tier and cannot
+		// import @teamscala/event-log across a same-tier edge — the boot layer
+		// owns that dependency.
+		const { procedureErrorReportInterceptor } = await import(
+			"@teamscala/orpc/procedure-error-report"
+		);
+		const { recordEvent } = await import("@teamscala/event-log/record-event");
+		const { configure: orpcConfigure } = await import(
+			"@teamscala/orpc/configure"
+		);
+		orpcConfigure({
+			procedureErrorRecorder: (record) =>
+				recordEvent({ kind: "orpc.procedure.failed", payload: record }),
+		});
+
 		const { RPCHandler } = await import("@orpc/server/fetch");
-		const handler = new RPCHandler(router as never, {});
+		const handler = new RPCHandler(router as never, {
+			interceptors: [procedureErrorReportInterceptor()] as never,
+		});
 
 		// The bootloader injects the service Prisma client into ORPC's configured
 		// primitive. Reading it through that surface keeps this mount on the same
@@ -109,7 +129,7 @@ export async function mountOrpcRouter(
 		// the EXPECTED state for services that have not migrated — db8 stays
 		// undefined and v7 procedures are untouched. One boot-time creation,
 		// closed over by the request handler (connects lazily on first query).
-		let db8: InjectedDb8 | undefined;
+		let db8: Db8Client | undefined;
 		try {
 			if (process.env.DATABASE_URL) {
 				const { createDbClientV8 } = await import(
@@ -175,7 +195,12 @@ export async function mountOrpcRouter(
 				import("@teamscala/db/work-items"),
 				import("@teamscala/email-client/client"),
 			]);
-			configureWorkItems({ emailSender: createEmailClient(), logger: log });
+			configureWorkItems({
+				// The injected contract is the template-send subset; the real
+				// client's send agrees at every call site ({to, template, vars}).
+				emailSender: createEmailClient() as never,
+				logger: log,
+			});
 		} catch (err) {
 			log.warn(
 				`[scala-install:${serviceSlug}] work-items email sender not wired: ${err instanceof Error ? err.message : err}`,
@@ -234,11 +259,10 @@ export async function mountOrpcRouter(
 					context: { prisma, db8, headers: c.req.raw.headers, resolveUser },
 				});
 				if (!result?.matched) return c.notFound();
-				// ORPC swallows procedure errors into a 500 response with a
-				// generic INTERNAL_SERVER_ERROR body. Without logging here the
-				// only signal is a fleet-wide spike in 500s with no traceback —
-				// measured 2026-09-04 when the regenerated prisma client shipped
-				// an empty orm and every model action returned a silent 500.
+				// Response-side signal only (a fleet-wide 500 spike with no
+				// traceback — measured 2026-09-04). The real error, its class and
+				// its stack are captured by the mount error hook above; this line
+				// stays for failures that reach the boundary without a throw.
 				if (result.response.status >= 500) {
 					log.error(
 						`[ORPC] ${c.req.method} ${c.req.path} → ${result.response.status}`,