@teamscala/service-boot 0.23.523 → 0.23.525

package/src/load-page-manifest.ts

@@ -1,28 +1,6 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Loads the service's GENERATED `src/page-manifest.ts` — the codegen output of
- * the `page-manifest` transform, emitted from `block_schema` rows. That file is
- * the single artefact describing which Puck components this service renders.
- *
- * This REPLACES `discover-blocks.ts`, a hand-written runtime scan that queried
- * block_schema at boot and dynamic-imported each row. Deleting it is the point.
- * The scan was introduced to survive one dead row, and it bought that by moving
- * a build-time, deterministic, generated fact into a runtime path with four
- * independent ways to silently resolve nothing: a registry read that answers
- * with an empty array instead of failing, an install probe that reports "not
- * installed" for installed packages, a `node_modules` lookup relative to
- * `process.cwd()`, and a per-block try/catch that swallows each failure into a
- * string nobody reads when the boot dies first. Measured 2026-09-03: 91 active
- * block_schema rows, a generated manifest carrying 63 blocks sitting on disk,
- * and the scan loading ZERO — for hours, across every UI service.
- *
- * Generation is the platform's answer to exactly this (`one-generator-pattern`,
- * `business-logic-is-rows-plus-executors`): a bad row fails codegen loudly, at
- * build time, with the file in front of you. It cannot present as a service
- * that boots and renders nothing.
  */
 
 import { join } from "node:path";
@@ -32,12 +10,6 @@ interface PageManifestModule {
 	components?: Record<string, RendererComponentEntry>;
 }
 
-/**
- * Reads the generated manifest's `components` export. Throws when the file is
- * absent or exports nothing — an empty manifest means codegen has not run for
- * this service, which is a build problem the operator must see named, not a
- * degraded runtime state to paper over.
- */
 export async function loadPageManifest(
 	serviceSlug: string,
 ): Promise<Record<string, RendererComponentEntry>> {

package/src/load-service-install-row.ts

@@ -1,11 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Loads the service_install registry row for a given service slug.
- * Uses registry.require() per Constitution Rule 11.
- * Schema is owned by @teamscala/db-validation (Rule 7).
  */
 
 import { getCache } from "@teamscala/db/registry/loader/cache/get-cache";
@@ -14,7 +9,6 @@ import {
 	RegistryValidationError,
 } from "@teamscala/db/registry/require";
 import { normalizeRegistryConfigObject } from "@teamscala/db/registry/validation";
-import type { ServiceInstallConfig } from "@teamscala/db-validation/registry-schemas/service-install";
 import {
 	enforceExplicitRenderMode,
 	ServiceInstallConfigSchema,
@@ -22,8 +16,32 @@ import {
 } from "@teamscala/db-validation/registry-schemas/service-install";
 import * as v from "valibot";
 
-export { ServiceInstallConfigSchema } from "@teamscala/db-validation/registry-schemas/service-install";
-export type { ServiceInstallConfig };
+const BOOT_ROW_KEYS = [
+	"access",
+	"api_routes",
+	"app_port",
+	"auth",
+	"block_packages",
+	"boot_hooks",
+	"brand_org",
+	"home_path",
+	"kind",
+	"orpc_router",
+	"portal_scoped",
+	"port",
+	"providers",
+	"render_mode",
+	"server_packages",
+	"websocket_routes",
+] as const;
+
+export const ServiceInstallBootSchema = v.object(
+	v.pick(ServiceInstallConfigSchema.pipe[0], BOOT_ROW_KEYS).entries,
+);
+
+export type ServiceInstallConfig = v.InferOutput<
+	typeof ServiceInstallBootSchema
+>;
 
 export interface LoadServiceInstallRowResult {
 	success: true;
@@ -54,9 +72,23 @@ export async function loadServiceInstallRow(
 			`service_install:${serviceSlug}`,
 		) as Record<string, unknown>;
 		enforceExplicitRenderMode(serviceSlug, rawConfig);
-		const config = v.parse(ServiceInstallConfigSchema, rawConfig);
+		const config = v.parse(ServiceInstallBootSchema, rawConfig);
 		return { success: true, config };
 	} catch (err) {
+		if (err instanceof v.ValiError) {
+			const issues = err.issues
+				.map((issue) => {
+					const path = v.getDotPath(issue);
+					return path ? `${path}: ${issue.message}` : issue.message;
+				})
+				.join("; ");
+			return {
+				success: false,
+				error: "validation_failed",
+				slug: serviceSlug,
+				message: `service_install row for "${serviceSlug}" has a key the boot reads missing or malformed: ${issues}`,
+			};
+		}
 		if (err instanceof RegistryMissingError) {
 			const sql = `INSERT INTO registry_entries (type, slug, config, is_active) VALUES ('service_install', '${serviceSlug}', '{"kind":"ui","render_mode":"public","port":null,"page_routes":[],"providers":[],"api_routes":[],"block_packages":[],"teamgbg_packages":[],"env_vars":[]}'::jsonb, true);`;
 			return {

package/src/module-not-found.ts

@@ -1,30 +1,13 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Classifies a failed dynamic import as "this candidate is absent" vs a real
- * error, for the server_package mount candidate chain. Extracted from
- * mount-server-packages so the classification is testable: as a closure it
- * could not be exercised, and it shipped wrong.
  */
 
-/** `@scope/name/sub/path.ts` -> `@scope/name`; `name/sub` -> `name`. */
 export function barePackageOf(specifier: string): string {
 	const parts = specifier.split("/");
 	return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 
-/**
- * True when the import failed because `requestedPath` itself is absent.
- *
- * Bun reports an unexported SUBPATH as `Cannot find package '<bare>'`, naming
- * the package rather than the subpath, so the bare name of THIS candidate
- * counts as not-found. Without that the first candidate's miss is
- * misclassified as fatal and the fallbacks never run (measured 2026-08-24:
- * scala-agents-ui crash-looped because cli-session exports ./boot/mount.ts and
- * not ./mount.ts). A transitive miss naming a DIFFERENT module still surfaces.
- */
 export function isModuleNotFound(err: unknown, requestedPath: string): boolean {
 	const msg =
 		(err as { message?: string })?.message ??

package/src/mount-orpc-router.ts

@@ -1,12 +1,6 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Mounts the composed ORPC app router (generated Prisma CRUD + custom fn routers)
- * at /api/rpc/* over HTTP via @orpc/server/fetch's RPCHandler.
- * Uses getAppRouter() from @teamscala/orpc/app-router which merges generated
- * routers plus the row-composed fn namespace (orpc-bundle from api_route rows).
  */
 
 import { join } from "node:path";
@@ -32,22 +26,12 @@ export async function mountOrpcRouter(
 	serviceSlug: string,
 ): Promise<OrpcMountResult | null> {
 	const log = getAppLogger();
-	// registerFnRouters() is retired: the row-composed bundle (orpc-bundle from
-	// api_route rows) is the sole fn source. The handwritten registration is
-	// fully shadowed by generated.fn (all families have rows) — keeping it
-	// would block generated-only procedures (auth, cacheAdmin, regions,
-	// realtime) from serving.
 	const routerPath = join(
 		process.cwd(),
 		"prisma/generated/orpc/routers/index.ts",
 	);
 	const schemaPath = join(process.cwd(), "prisma/schema.prisma");
 
-	// ORPC forward mode: when SCALA_ORPC_FORWARD_URL is set and there is no
-	// local bundle, /api/rpc/* proxies to the central ORPC surface instead of
-	// mounting a per-service router. This is the collapse's consolidation path —
-	// services shed their local bundle and the central surface serves all
-	// row-composed procedures.
 	const forwardUrl = process.env.SCALA_ORPC_FORWARD_URL;
 	if (!await Bun.file(routerPath).exists() && forwardUrl) {
 		const base = forwardUrl.replace(/\/+$/, "");
@@ -58,7 +42,7 @@ export async function mountOrpcRouter(
 				method: c.req.method,
 				headers: c.req.raw.headers,
 				body: c.req.raw.body,
-				// @ts-ignore — duplex is required for streaming bodies in Bun
+				// @ts-ignore duplex is required for streaming bodies in Bun
 				duplex: "half",
 			});
 			return new Response(res.body, {
@@ -73,14 +57,6 @@ export async function mountOrpcRouter(
 		return { routeCount: 0 };
 	}
 
-	// No generated ORPC router is the EXPECTED state for daemon-only / boot-hook
-	// services (session-picker, dep-sync, etc.) that own no DB schema or
-	// api_routes — they serve no /api/rpc surface. Skip silently: importing a
-	// nonexistent module would throw into the catch below and surface a
-	// misleading "ORPC router not mounted" WARN on every boot. The catch is
-	// 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 (!await Bun.file(routerPath).exists()) {
 		if (await Bun.file(schemaPath).exists()) {
 			throw new Error(
@@ -97,12 +73,6 @@ 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"
 		);
@@ -120,24 +90,12 @@ export async function mountOrpcRouter(
 			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
-		// dependency boundary as the generated procedures.
 		const { getPrisma: getConfiguredPrisma } = await import(
 			"@teamscala/orpc/configure"
 		);
 
-		// Coexistence (Prisma 8 migration): create the v8 chained client when
-		// the shared platform contract ships inside @teamscala/db. Absence is
-		// 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: Db8Client | undefined;
 		try {
-			// Named-need address (wrong-database guard, 2026-09-27): the tenant
-			// plane by name through @teamscala/db's resolver, never an env key
-			// read at this call site. Null = the deploy wrote nothing for this
-			// plane, and db8 stays undefined on the existing absence path.
 			const databaseUrl = resolveDbUrlOrNull("tenant");
 			if (databaseUrl) {
 				const { createDbClientV8 } = await import(
@@ -147,9 +105,6 @@ export async function mountOrpcRouter(
 					connectionString: databaseUrl,
 					serviceName: serviceSlug,
 				})) as never;
-				// Register for db-core internals (registry loaders, raw fallbacks)
-				// routing v8-first via getDb8() — the same coexistence shape as
-				// the RPC context injection above.
 				const { registerDb8 } = await import("@teamscala/db/db8-registry");
 				registerDb8(db8 as never);
 			}
@@ -160,26 +115,9 @@ export async function mountOrpcRouter(
 			db8 = undefined;
 		}
 
-		// Bridge the composed router into tool-executor so in-process tool
-		// dispatch (chat agents' work_items/meetings/agreements/proposals
-		// tools, etc.) resolves against this service's ORPC router + Prisma
-		// client. Without this every ORPC tool call throws
-		// "app router provider not configured". Parallel to dev-mcp-boot's
-		// configureToolExecutor. Calls getAppRouter() fresh each time (not a
-		// boot-time capture) so the tool-executor always resolves the CURRENT
-		// memoized router — the tool-generator listener may regenerate the
-		// ORPC router and call clearAppRouterCache() after boot, producing a
-		// new router object that a captured closure would miss.
 		const { configure: configureToolExecutor } = await import(
 			"@teamscala/tool-executor/configure"
 		);
-		// The caller-identity and secret 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 retired
-		// @teamscala/host-command-bus invoker injection no longer happens: the
-		// bus is retired, and host_command tools execute through the native
-		// in-process coding path inside tool-executor.
 		const [{ getCallerContext }, { decryptSecretConfig }] =
 			await Promise.all([
 				import("@teamscala/mcp-multi-session/caller-context"),
@@ -192,19 +130,12 @@ export async function mountOrpcRouter(
 			decryptSecretConfig: (raw) => decryptSecretConfig(raw as never),
 		});
 
-		// The fn capability primitives (foundation tier) cannot import the email
-		// client, so the boot layer injects the real sender — the same shape the
-		// bootloader already uses for getPrisma. Until configured, fn.workItems
-		// notification procedures degrade to { notified: 0 } with an error log
-		// (never throw).
 		try {
 			const [{ configureWorkItems }, { createEmailClient }] = await Promise.all([
 				import("@teamscala/db/work-items"),
 				import("@teamscala/email-client/client"),
 			]);
 			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,
 			});
@@ -232,17 +163,7 @@ export async function mountOrpcRouter(
 					id: session.user.id,
 					name: session.user.name ?? undefined,
 					email: session.user.email,
-					// The active organisation lives on the SESSION
-					// (activeOrganizationId, set at sign-in by scala-otp's
-					// session.create hook), NOT on the user object — getSession's
-					// ResolvedSession.user carries no organisationId. Reading the
-					// user field left organisationId always null, so the generated
-					// router's org-scope gate 403'd every non-super-admin write
-					// ("Organization membership required") on the public-HTTP path.
 					organisationId: session.session.activeOrganizationId ?? null,
-					// better-auth's admin plugin issues role "admin"; the platform
-					// also uses "super-admin"/"super_admin". All three are platform
-					// super-admins for ORPC org-scope bypass.
 					isSuperAdmin:
 						role === "super_admin" ||
 						role === "super-admin" ||
@@ -266,10 +187,6 @@ export async function mountOrpcRouter(
 					context: { prisma, db8, headers: c.req.raw.headers, resolveUser },
 				});
 				if (!result?.matched) return c.notFound();
-				// 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}`,
@@ -279,16 +196,6 @@ export async function mountOrpcRouter(
 			},
 		);
 
-		// THE OpenAPI CONTRACT, served BESIDE the RPC — a GET on the same prefix,
-		// generated from the router object mounted below, so the document and the
-		// handler cannot describe different surfaces. Order is free: the methods
-		// never overlap (`app.post` matches POST alone).
-		//
-		// Gated by openApiContractAuthorised, which refuses a proxied request as
-		// well as a wrong key (guard auth-helpers-fail-closed), so only an
-		// internal caller — the MCP gateway — reaches this. Its own facts come
-		// from openApiContractOptions; both units carry the reasoning, and
-		// contract rows state their behaviour.
 		app.get("/api/rpc/openapi.json", async (c) => {
 			const header = (name: string) => c.req.header(name) ?? null;
 			if (

package/src/mount-server-packages.ts

@@ -1,13 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Walks `service_install.server_packages[]`, dynamic-imports each, and calls
- * its `mount(ctx)` function. Server packages register handlers / boot hooks /
- * scheduled jobs / WS routes via the MountContext exposed in ctx; the
- * resulting MountRegistry is consumed by register-api-routes /
- * register-ws-routes / run-boot-hook-list / start-scheduled-jobs.
  */
 
 /**
@@ -96,9 +89,6 @@ export async function mountServerPackages(
 						lastNotFound = err;
 						continue;
 					}
-					// Real error (syntax, runtime, transitive resolution failure inside the
-					// loaded module) — surface it directly. Swallowing here is what hides
-					// the true cause behind a misleading "cannot find <pkg>" further down.
 					throw new BootFatalError(
 						"mount-server-packages",
 						serviceSlug,
@@ -129,30 +119,6 @@ export async function mountServerPackages(
 			}
 		} catch (err) {
 			if (err instanceof BootFatalError) throw err;
-			// A PLUGIN THAT FAILS TO MOUNT IS UNAVAILABLE, NOT FATAL. `crash-isolation`
-			// states the law directly — "a failure in one package does not crash the
-			// host" — and names the plugin failure domain: "a broken plugin degrades
-			// to 'that plugin unavailable'". This arm used to wrap ANY mount error in
-			// a BootFatalError, so one plugin's missing config killed a whole service.
-			//
-			// MEASURED 2026-09-07: scala-agents-ui, the operator's fleet monitoring UI,
-			// booted through db, auth, routes and every other server_package, then died
-			// at @teamscala/opencode because OPENCODE_SERVER_URL was absent. systemd
-			// retried five times and gave up, agents.scala.business served 502, and the
-			// operator lost sight of his fleet — over one optional integration missing
-			// one variable, on a page that needs no opencode connection to render.
-			//
-			// THE ASYMMETRY DECIDES IT. A service that boots without one plugin still
-			// serves every route that plugin did not own, and the gap is loud in this
-			// log line and counted in the summary below. A service that refuses to boot
-			// serves NOTHING — including the surface that would have explained why.
-			//
-			// NOT-FOUND STAYS FATAL, deliberately: that arm is above and untouched. A
-			// package that LOADS and then throws is a broken plugin, which is this
-			// case. A package that cannot be resolved at all means the declared
-			// dependency set was never installed — an install-integrity failure, where
-			// booting a half-installed service would serve wrong results while looking
-			// healthy.
 			degraded.push(pkg);
 			log.error(
 				`[scala-install:${serviceSlug}] server_package "${pkg}" UNAVAILABLE — mount failed; ` +
@@ -165,8 +131,6 @@ export async function mountServerPackages(
 		`[scala-install:${serviceSlug}] Registered ${mountRegistry.handlers.size} handler(s), ` +
 			`${mountRegistry.wsRoutes.size} ws route(s), ` +
 			`${mountRegistry.bootHooks.size} boot hook(s)` +
-			// NAMED, NEVER COUNTED. A bare "1 degraded" sends the reader hunting for
-			// which one; the name is the whole value of the line.
 			(degraded.length > 0
 				? `, ${degraded.length} server_package(s) UNAVAILABLE: ${degraded.join(", ")}`
 				: ""),

package/src/mount.ts

@@ -1,9 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Server-package mount for opt-in service-boot watchdogs.
  */
 
 import type { MountContext } from "@teamscala/os/runtime-contracts/mount-context";

package/src/mutable-app-ref.ts

@@ -1,34 +1,17 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Mutable app reference for two-phase boot. Allows swapping the Hono app
- * atomically after building the full app in the background. The initial app
- * is a minimal tool-only surface (ORPC, data routes) that starts serving
- * immediately; the full app (pages, hydration) is built off-to-the-side and
- * swapped in once complete.
- *
- * Thread-safety: Bun is single-threaded, so a simple module-level variable
- * is sufficient. Atomics are not needed.
  */
 
 import type { Hono } from "hono";
 let currentApp: Hono | null = null;
 let appLabel = "initial";
 
-/**
- * Create a new mutable app reference initialized with the provided app.
- * This should be called once at boot time.
- */
 export function initMutableAppRef(initialApp: Hono, label: string): void {
 	currentApp = initialApp;
 	appLabel = label;
 }
 
-/**
- * Get the current app. Throws if the ref hasn't been initialized.
- */
 export function getApp(): Hono {
 	if (!currentApp) {
 		throw new Error("Mutable app reference not initialized");
@@ -36,10 +19,6 @@ export function getApp(): Hono {
 	return currentApp;
 }
 
-/**
- * Atomically swap the app to a new instance. This is called after the
- * full app is built in the background. Returns the previous label for logging.
- */
 export function swapApp(newApp: Hono, newLabel: string): string {
 	const oldLabel = appLabel;
 	currentApp = newApp;