@teamscala/service-boot 0.23.546 → 0.23.547

package/package.json

@@ -27,7 +27,7 @@
 	"repository": "https://github.com/teamgbg/service-boot",
 	"sideEffects": false,
 	"type": "module",
-	"version": "0.23.546",
+	"version": "0.23.547",
 	"dependencies": {
 		"@orpc/openapi": "*",
 		"@orpc/server": "*",

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

@@ -18,7 +18,6 @@ import * as v from "valibot";
 
 const BOOT_ROW_KEYS = [
 	"access",
-	"api_routes",
 	"app_port",
 	"auth",
 	"block_packages",
@@ -90,7 +89,7 @@ export async function loadServiceInstallRow(
 			};
 		}
 		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);`;
+			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":[],"block_packages":[],"teamgbg_packages":[],"env_vars":[]}'::jsonb, true);`;
 			return {
 				success: false,
 				error: "row_not_found",

package/src/orpc-contract-rows.json

@@ -314,6 +314,213 @@
       "suite_type": "function_call",
       "slug": "service-boot:absent-manifest-verdict-reserves-never-ran"
     },
+    {
+      "args": [
+        [
+          {
+            "slug": "npm-registry-hook",
+            "config": {
+              "path": "/webhooks/npm/registry",
+              "method": "POST",
+              "handler": "npm-registry-hook",
+              "service": "scala-sync-worker",
+              "auth_required": false
+            }
+          },
+          {
+            "slug": "email.send",
+            "config": {
+              "path": "/api/rpc/email/send",
+              "method": "POST",
+              "service": "scala-email-sender",
+              "handler_slug": "email.send",
+              "auth_required": true
+            }
+          }
+        ],
+        "scala-sync-worker",
+        [
+          "npm-registry-hook"
+        ]
+      ],
+      "note": "Bug 01a15334 (Joe's Developer, delivery 01a15336): the shape of the row that was declared and never served - config.handler (not handler_slug) on POST /webhooks/npm/registry for scala-sync-worker.",
+      "label": "a row naming its mount handler in config.handler is selected for its own service and maps onto the handler registry",
+      "expect": [
+        {
+          "slug": "npm-registry-hook",
+          "mount": {
+            "path": "/webhooks/npm/registry",
+            "method": "post",
+            "handlerSlug": "npm-registry-hook"
+          },
+          "service": "scala-sync-worker",
+          "notMounted": null
+        }
+      ],
+      "export": "selectServiceApiRoutes",
+      "module": "src/select-service-api-routes.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "service-boot:api-route-config-handler-maps-onto-the-mount-registry"
+    },
+    {
+      "args": [
+        [
+          {
+            "slug": "email.send",
+            "config": {
+              "path": "/api/rpc/email/send",
+              "method": "POST",
+              "service": "scala-email-sender",
+              "handler_slug": "email.send",
+              "auth_required": true
+            }
+          }
+        ],
+        "scala-email-sender",
+        [
+          "npm-registry-hook"
+        ]
+      ],
+      "note": "api_route/email.send names handler_slug email.send, but no server_package in the workspace registers it and service_install/scala-email-sender declares no server_packages. Boot reports it by name on every start instead of claiming the route is served.",
+      "label": "a row naming a handler no mounted package registered is named as unserved instead of silently 404ing or bricking the service",
+      "expect": [
+        {
+          "slug": "email.send",
+          "mount": null,
+          "service": "scala-email-sender",
+          "notMounted": "handler-not-mounted"
+        }
+      ],
+      "export": "selectServiceApiRoutes",
+      "module": "src/select-service-api-routes.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "service-boot:api-route-row-naming-an-unmounted-handler-is-reported-unserved"
+    },
+    {
+      "args": [
+        [
+          {
+            "slug": "npm-registry-hook",
+            "config": {
+              "path": "/webhooks/npm/registry",
+              "method": "POST",
+              "handler": "npm-registry-hook",
+              "service": "scala-sync-worker",
+              "auth_required": false
+            }
+          }
+        ],
+        "scala-sync-worker-ts-dev",
+        [
+          "npm-registry-hook"
+        ]
+      ],
+      "note": "Raw string equality on the deployable name matched at most one lane and failed silently (capability-slug.ts incident): the row names the capability, the lane arrives as <capability>-<lang>-<tier>.",
+      "label": "a dev-lane service is served the rows its capability declares, the join select-service-routes.ts already makes for page_route",
+      "expect": [
+        {
+          "slug": "npm-registry-hook",
+          "mount": {
+            "path": "/webhooks/npm/registry",
+            "method": "post",
+            "handlerSlug": "npm-registry-hook"
+          },
+          "service": "scala-sync-worker",
+          "notMounted": null
+        }
+      ],
+      "export": "selectServiceApiRoutes",
+      "module": "src/select-service-api-routes.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "service-boot:api-route-row-reaches-the-dev-lane-through-the-capability-slug"
+    },
+    {
+      "args": [
+        [
+          {
+            "slug": "fn-chat-complete",
+            "config": {
+              "path": "/api/rpc/fn/chat/complete",
+              "method": "POST",
+              "service": "scala-ai",
+              "handler_type": "orpc_fn",
+              "auth_required": true
+            }
+          }
+        ],
+        "scala-ai",
+        [
+          "chat-stream"
+        ]
+      ],
+      "note": "handler_type orpc_fn rows are served by the generated ORPC router (orpc-bundle.pkl), not by a mount handler; boot must not claim them or fail on them.",
+      "label": "a row that names no mount handler is reported as declared, never mounted onto the mount registry",
+      "expect": [
+        {
+          "slug": "fn-chat-complete",
+          "mount": null,
+          "service": "scala-ai",
+          "notMounted": "declares-no-mount-handler"
+        }
+      ],
+      "export": "selectServiceApiRoutes",
+      "module": "src/select-service-api-routes.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "service-boot:api-route-row-without-a-mount-handler-is-declared-not-mounted"
+    },
+    {
+      "args": [
+        [
+          {
+            "slug": "npm-registry-hook",
+            "config": {
+              "path": "/webhooks/npm/registry",
+              "method": "POST",
+              "handler": "npm-registry-hook",
+              "service": "scala-sync-worker",
+              "auth_required": false
+            }
+          },
+          {
+            "slug": "scala-forms-get--api-places-autocomplete",
+            "config": {
+              "path": "/api/places/autocomplete",
+              "method": "GET",
+              "service": "scala-forms",
+              "handler_slug": "geocode-autocomplete",
+              "auth_required": false
+            }
+          }
+        ],
+        "scala-forms",
+        [
+          "geocode-autocomplete"
+        ]
+      ],
+      "note": "A row belonging to a different service must not leak into this service's route table or its boot log.",
+      "label": "another service's row is neither mounted nor reported - selection is by this service's capability alone",
+      "expect": [
+        {
+          "slug": "scala-forms-get--api-places-autocomplete",
+          "mount": {
+            "path": "/api/places/autocomplete",
+            "method": "get",
+            "handlerSlug": "geocode-autocomplete"
+          },
+          "service": "scala-forms",
+          "notMounted": null
+        }
+      ],
+      "export": "selectServiceApiRoutes",
+      "module": "src/select-service-api-routes.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "service-boot:api-route-rows-of-another-service-are-not-selected"
+    },
     {
       "args": [
         "@teamscala/cli-session"

package/src/register-api-routes.ts

@@ -3,112 +3,118 @@
  * @status handwritten
  */
 
-import type { ServiceInstallConfig } from "./load-service-install-row";
+import { getEntriesByType } from "@teamscala/db/registry/accessors";
+import { ApiRouteConfigSchema } from "@teamscala/registry-schemas/registry-schemas/api-route";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { BootFatalError } from "@teamscala/os/errors/boot-error";
+import type { ServiceInstallConfig } from "./load-service-install-row";
 import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
 import type { Context, Hono } from "hono";
 import { getConnInfo } from "hono/bun";
 import { CALLER_HEADERS } from "@teamscala/os/contracts/mcp";
+import {
+	selectServiceApiRoutes,
+	type ApiRouteRowShape,
+} from "./select-service-api-routes.ts";
+import * as v from "valibot";
 
-// From CALLER_HEADERS, never a literal: this name is one end of a contract the
-// gateway's caller-resolution reads, and a literal stores it twice. The
-// 2026-08-02 outage was that exact drift on a sibling header (reader on
-// `x-user-id`, writer on `x-caller-user-id`), and it took every tool on the
-// cloud MCP down once the branch masking it was closed.
 const REMOTE_PORT_HEADER = CALLER_HEADERS.REMOTE_PORT;
-// Verified socket-peer address (unforgeable transport origin). Sanitized
-// (client-supplied value deleted) then set from getConnInfo so handlers that
-// receive only a Request (e.g. mcp-tool-runtime/mount.ts) can gate on the
-// genuine transport origin per no-client-controlled-trust-signals — an external
-// attacker cannot make their TCP connection appear on the server's loopback.
 const REMOTE_ADDR_HEADER = CALLER_HEADERS.REMOTE_ADDRESS;
 
+function readApiRouteRows(log: ReturnType<typeof getAppLogger>): ApiRouteRowShape[] {
+	const rows: ApiRouteRowShape[] = [];
+	for (const entry of getEntriesByType("api_route")) {
+		if (!entry.is_active) continue;
+		const parsed = v.safeParse(ApiRouteConfigSchema, entry.config);
+		if (!parsed.success) {
+			const issues = parsed.issues
+				.map((issue) => {
+					const path = v.getDotPath(issue);
+					return path ? `${path}: ${issue.message}` : issue.message;
+				})
+				.join("; ");
+			log.error(
+				`[register-api-routes] api_route "${entry.slug}" does not satisfy its own schema, so none of its routes are served: ${issues}`,
+			);
+			continue;
+		}
+		rows.push({ slug: entry.slug, config: parsed.output });
+	}
+	return rows;
+}
+
 export function registerApiRoutes(
 	app: Hono,
-	config: ServiceInstallConfig,
+	_config: ServiceInstallConfig,
 	mountRegistry: MountRegistry,
 	serviceSlug: string,
 ): number {
 	const log = getAppLogger();
+	const decisions = selectServiceApiRoutes(
+		readApiRouteRows(log),
+		serviceSlug,
+		[...mountRegistry.handlers.keys()],
+	);
 	let count = 0;
-	for (const route of config.api_routes ?? []) {
-		const handler = mountRegistry.handlers.get(route.handler_slug);
-		if (!handler) {
-			throw new BootFatalError(
-				"register-api-routes",
-				serviceSlug,
-				`api_route "${route.method} ${route.path}" references handler_slug "${route.handler_slug}" but no server_package registered it`,
-			);
-		}
-		const method = route.method.toLowerCase() as
-			| "get"
-			| "post"
-			| "put"
-			| "delete"
-			| "patch";
-		(app as never as Record<string, (path: string, h: never) => void>)[method](
-			route.path,
-			(async (c: Context) => {
-				let req: Request = c.req.raw;
-				try {
-					if (typeof c.env !== "object" || c.env === null) {
-						log.debug(
-							`[register-api-routes] getConnInfo skipped: c.env is ${typeof c.env}`,
-						);
-					} else {
-						const info = getConnInfo(c);
-						const port = info?.remote?.port;
-						const address = info?.remote?.address ?? null;
-						// Port: set when not already present (caller-identity pane
-						// resolution preserves a chained value). Address: sanitize +
-						// re-set ONLY when getConnInfo returned one — the canonical
-						// address injection lives in service-runtime's serve.ts
-						// (server.requestIP, which reliably returns address; Hono's
-						// getConnInfo does not on Bun). Touching the address here
-						// only when we can re-verify avoids clobbering serve.ts's
-						// injection.
-						const needsPort =
-							typeof port === "number" &&
-							port > 0 &&
-							!req.headers.has(REMOTE_PORT_HEADER);
-						if (address !== null || needsPort) {
-							const headers = new Headers(req.headers);
-							if (address) {
-								headers.delete(REMOTE_ADDR_HEADER);
-								headers.set(REMOTE_ADDR_HEADER, String(address));
-							}
-							if (needsPort) headers.set(REMOTE_PORT_HEADER, String(port));
-							req = new Request(req.url, {
-								method: req.method,
-								headers,
-								body: req.body,
-							});
+	for (const decision of decisions) {
+		const mount = decision.mount;
+		if (!mount) continue;
+		const handler = mountRegistry.handlers.get(mount.handlerSlug);
+		if (!handler) continue;
+		const register = app as unknown as Record<
+			string,
+			(path: string, handler: (c: Context) => Promise<Response>) => void
+		>;
+		register[mount.method](mount.path, async (c: Context) => {
+			let req: Request = c.req.raw;
+			try {
+				if (typeof c.env !== "object" || c.env === null) {
+					log.debug(
+						`[register-api-routes] getConnInfo skipped: c.env is ${typeof c.env}`,
+					);
+				} else {
+					const info = getConnInfo(c);
+					const port = info?.remote?.port;
+					const address = info?.remote?.address ?? null;
+					const needsPort =
+						typeof port === "number" &&
+						port > 0 &&
+						!req.headers.has(REMOTE_PORT_HEADER);
+					if (address !== null || needsPort) {
+						const headers = new Headers(req.headers);
+						if (address) {
+							headers.delete(REMOTE_ADDR_HEADER);
+							headers.set(REMOTE_ADDR_HEADER, String(address));
 						}
-						log.debug(
-							`[register-api-routes] getConnInfo port=${port ?? "undefined"} address=${address ?? "undefined"}`,
-						);
+						if (needsPort) headers.set(REMOTE_PORT_HEADER, String(port));
+						req = new Request(req.url, {
+							method: req.method,
+							headers,
+							body: req.body,
+						});
 					}
-				} catch (e) {
-					getAppLogger().error(
-						`[register-api-routes] getConnInfo failed: ${e}`,
+					log.debug(
+						`[register-api-routes] getConnInfo port=${port ?? "undefined"} address=${address ?? "undefined"}`,
 					);
 				}
-				const params = c.req.param();
-				return handler(req, params);
-			}) as never,
-		);
+			} catch (e) {
+				log.error(`[register-api-routes] getConnInfo failed: ${e}`);
+			}
+			return handler(req, c.req.param());
+		});
 		count++;
 	}
 
-	// NO hand-rolled OPTIONS/CORS here: two-phase-minimal-app registers the
-	// official hono/cors middleware GLOBALLY before this runs, and its OPTIONS
-	// branch answers preflights without calling next() — a hand preflight
-	// handler registered here is shadowed dead code (measured: zero
-	// invocations across trusted/no/foreign-origin preflights, bun probe
-	// 2026-09-27). The middleware also decorates ACTUAL cross-origin
-	// responses and reflects origins only inside the cookie domain — the
-	// dead copy reflected ANY origin with credentials.
+	const unserved = decisions.filter((decision) => decision.mount === null);
+	if (unserved.length > 0) {
+		log.warn(
+			`[scala-install:${serviceSlug}] ${unserved.length} api_route row(s) naming this service are NOT served: ${unserved
+				.map((decision) => `"${decision.slug}" (${decision.notMounted})`)
+				.join(", ")}`,
+		);
+	}
+	log.info(
+		`[scala-install:${serviceSlug}] registered ${count} api_route mount(s) from registry rows`,
+	);
 
 	return count;
 }

package/src/select-service-api-routes.ts

@@ -0,0 +1,82 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ */
+
+import { toCapabilitySlug } from "./capability-slug.ts";
+
+export interface ApiRouteRowShape {
+	slug: string;
+	config: {
+		service: string;
+		method: string;
+		path: string;
+		handler?: string;
+		handler_slug?: string;
+	};
+}
+
+export type MountMethod = "get" | "post" | "put" | "delete" | "patch";
+
+export interface MountShape {
+	method: MountMethod;
+	path: string;
+	handlerSlug: string;
+}
+
+export type NotMountedBecause = "declares-no-mount-handler" | "handler-not-mounted";
+
+export interface ApiRouteDecision {
+	slug: string;
+	service: string;
+	mount: MountShape | null;
+	notMounted: NotMountedBecause | null;
+}
+
+const MOUNT_METHODS: ReadonlySet<string> = new Set([
+	"get",
+	"post",
+	"put",
+	"delete",
+	"patch",
+]);
+
+export function selectServiceApiRoutes<T extends ApiRouteRowShape>(
+	rows: readonly T[],
+	serviceSlug: string,
+	mountedHandlers: readonly string[],
+): ApiRouteDecision[] {
+	const capability = toCapabilitySlug(serviceSlug);
+	const mounted = new Set(mountedHandlers);
+	const decisions: ApiRouteDecision[] = [];
+	for (const row of rows) {
+		const service = row.config.service;
+		if (toCapabilitySlug(service) !== capability) continue;
+		const handlerSlug = row.config.handler ?? row.config.handler_slug;
+		if (handlerSlug === undefined) {
+			decisions.push({
+				slug: row.slug,
+				service,
+				mount: null,
+				notMounted: "declares-no-mount-handler",
+			});
+			continue;
+		}
+		const method = row.config.method.toLowerCase();
+		if (!MOUNT_METHODS.has(method)) {
+			throw new Error(
+				`api_route "${row.slug}" declares method "${row.config.method}", which no HTTP surface can serve`,
+			);
+		}
+		const isMounted = mounted.has(handlerSlug);
+		decisions.push({
+			slug: row.slug,
+			service,
+			mount: isMounted
+				? { method: method as MountMethod, path: row.config.path, handlerSlug }
+				: null,
+			notMounted: isMounted ? null : "handler-not-mounted",
+		});
+	}
+	return decisions;
+}