@teamscala/service-boot 0.23.501 → 0.23.503

package/package.json

@@ -1130,5 +1130,5 @@
   "repository": "https://github.com/teamgbg/service-boot",
   "sideEffects": false,
   "type": "module",
-  "version": "0.23.501"
+  "version": "0.23.503"
 }

package/src/capability-slug.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { toCapabilitySlug } from "./capability-slug.ts";
+
+describe("toCapabilitySlug", () => {
+	test("strips the language+tier suffix from a dev deployable", () => {
+		expect(toCapabilitySlug("scala-projects-bun-dev")).toBe("scala-projects");
+		expect(toCapabilitySlug("scala-ai-bun-dev")).toBe("scala-ai");
+		expect(toCapabilitySlug("scala-image-optimizer-rust-dev")).toBe(
+			"scala-image-optimizer",
+		);
+	});
+
+	test("strips the language+tier suffix from a prod deployable", () => {
+		expect(toCapabilitySlug("scala-projects-bun-prod")).toBe("scala-projects");
+		expect(toCapabilitySlug("scala-messaging-service-rust-prod")).toBe(
+			"scala-messaging-service",
+		);
+	});
+
+	test("returns an already-capability slug unchanged", () => {
+		// The prod lane is still bare while the tier migration is in flight, so
+		// the SAME function must be correct before and after the rename lands.
+		expect(toCapabilitySlug("scala-projects")).toBe("scala-projects");
+		expect(toCapabilitySlug("scala-otp")).toBe("scala-otp");
+	});
+
+	test("both lanes of one application normalize to the same identity", () => {
+		// This is the property the page_route join depends on.
+		expect(toCapabilitySlug("scala-projects-bun-dev")).toBe(
+			toCapabilitySlug("scala-projects"),
+		);
+		expect(toCapabilitySlug("scala-quiz-bun-dev")).toBe(
+			toCapabilitySlug("scala-quiz-bun-prod"),
+		);
+	});
+
+	test("leaves a name whose tail is not the closed grammar alone", () => {
+		// Not a language segment.
+		expect(toCapabilitySlug("scala-node-dev")).toBe("scala-node-dev");
+		// Not a tier segment.
+		expect(toCapabilitySlug("scala-bun-staging")).toBe("scala-bun-staging");
+		// Too short to carry both segments.
+		expect(toCapabilitySlug("bun-dev")).toBe("bun-dev");
+		expect(toCapabilitySlug("supavisor")).toBe("supavisor");
+	});
+});

package/src/capability-slug.ts

@@ -0,0 +1,59 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Deployable slug -> capability slug.
+ *
+ * A DEPLOYABLE is named `<capability>-<language>-<tier>`
+ * (`deployables-carry-language-and-tier`): `scala-projects-bun-dev` and
+ * `scala-projects-bun-prod` are two DEPLOYMENTS of one APPLICATION. The
+ * ecosystem generator emits that name into `SERVICE_SLUG` per lane, so one
+ * service arrives here under a DIFFERENT identity in each lane.
+ *
+ * A `page_route` row describes the APPLICATION url space, which is the same
+ * in both lanes, so it carries the CAPABILITY name and there is exactly one
+ * row per route rather than one per lane. Joining the two by raw string
+ * equality therefore matches at most one lane, and does so SILENTLY:
+ * measured 2026-09-11, 8 of 10 dev UI services registered ZERO page routes
+ * and served 404 on every path -- including `/sign-in` -- while booting
+ * clean and reporting healthy, because the dev lane ran as
+ * `scala-projects-bun-dev` while every page_route row said `scala-projects`.
+ *
+ * Both sides normalize through this one function, so the join is
+ * tier-agnostic by construction and a row may name either form.
+ *
+ * The suffix grammar is a CLOSED SET defined by doctrine and emitted by the
+ * generator, so this is a parse of a documented contract rather than a
+ * pattern heuristic. A slug that does not end in one is already a capability
+ * name and is returned unchanged -- which is why this is correct both BEFORE
+ * the tier migration completes (prod is still bare `scala-projects`) and
+ * after it (prod becomes `scala-projects-bun-prod`).
+ */
+
+/** Language segment of a deployable name. */
+const LANGUAGES = ["bun", "rust"] as const;
+
+/** Tier segment of a deployable name. */
+const TIERS = ["dev", "prod"] as const;
+
+type Language = (typeof LANGUAGES)[number];
+type Tier = (typeof TIERS)[number];
+
+/**
+ * The capability half of a deployable slug.
+ *
+ * `scala-projects-bun-dev`  -> `scala-projects`
+ * `scala-projects-bun-prod` -> `scala-projects`
+ * `scala-projects`          -> `scala-projects` (already a capability name)
+ */
+export function toCapabilitySlug(slug: string): string {
+	const parts = slug.split("-");
+	if (parts.length < 3) return slug;
+
+	const tier = parts[parts.length - 1] as Tier;
+	const language = parts[parts.length - 2] as Language;
+	if (!TIERS.includes(tier) || !LANGUAGES.includes(language)) return slug;
+
+	return parts.slice(0, -2).join("-");
+}

package/src/register-page-routes.ts

@@ -14,6 +14,7 @@
  * `page_route` rows (all 9 services carry empty arrays).
  */
 
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import type { Hono } from "hono";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import type { RenderModeLiteral } from "./page-route-shell-types.ts";
@@ -58,5 +59,19 @@ export async function registerPageRoutes(
 		portalScoped,
 	});
 
+	// A kind:ui SERVICE THAT RESOLVES NO PAGES IS AIMED AT NOTHING, and until
+	// now that state booted clean: zero matched rows was treated as a valid
+	// shape, so the service reported healthy and answered 404 on every path,
+	// /sign-in included. Measured 2026-09-11: 8 of 10 dev UI services sat in
+	// exactly this state and nothing anywhere said so
+	// (`a-component-may-not-report-a-state-it-has-not-verified`).
+	if ((config as { kind?: string }).kind === "ui" && registryPatterns.length === 0) {
+		throw new BootFatalError(
+			"ui-service.no-page-routes",
+			serviceSlug,
+			`No active page_route row resolves to this service. A kind:ui service must serve at least one page. Check that a page_route row names this capability (rows are matched on the capability half of the deployable slug -- see capability-slug.ts).`,
+		);
+	}
+
 	return registryPatterns;
 }

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

@@ -23,6 +23,7 @@
 
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { toCapabilitySlug } from "./capability-slug.ts";
 
 export async function registerPageServerClient(
 	serviceSlug: string,
@@ -71,9 +72,20 @@ export async function registerPageServerClient(
 				);
 				// 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(
 					"service_schema",
-					serviceSlug as never,
+					toCapabilitySlug(serviceSlug) as never,
 					undefined as never,
 				)) as
 					| { models?: string[] }

package/src/register-registry-page-route.ts

@@ -31,6 +31,7 @@ import {
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
 import { bindPageHandler } from "./bind-page-handler.ts";
+import { selectServiceRoutes } from "./select-service-routes.ts";
 import { resolveRequestGraph } from "./register-registry-page-route/resolve-request-graph.ts";
 import { stampSessionContext } from "./register-registry-page-route/stamp-session-context.ts";
 import { runContentGatesForPage } from "./register-registry-page-route/run-content-gates.ts";
@@ -134,29 +135,9 @@ export async function registerRegistryPageRoute(
 		"page_route",
 		PageRouteConfigSchema,
 	);
-	const serviceRoutes = allRoutes.filter(
-		(r) => r.config.service === serviceSlug,
-	);
+	const serviceRoutes = selectServiceRoutes(allRoutes, serviceSlug);
 	if (serviceRoutes.length === 0) return [];
 
-	// Sort routes so more specific patterns register before wildcard/param routes.
-	// Hono matches by registration order, so `/*` (the portal catchall) registered
-	// before `/sign-in` would swallow the sign-in page and render it inside the
-	// PortalTemplate instead of the standalone PublicTemplate shell.
-	serviceRoutes.sort((a, b) => {
-		const pa = a.config.pattern;
-		const pb = b.config.pattern;
-		// Wildcard `/*` goes last
-		if (pa === "/*") return 1;
-		if (pb === "/*") return -1;
-		// Param routes `/:param` sort after literal routes
-		const aIsLiteral = !pa.includes(":") && !pa.includes("*");
-		const bIsLiteral = !pb.includes(":") && !pb.includes("*");
-		if (aIsLiteral && !bIsLiteral) return -1;
-		if (!aIsLiteral && bIsLiteral) return 1;
-		return 0;
-	});
-
 	const registeredPatterns: string[] = [];
 
 	for (const routeRow of serviceRoutes) {

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

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { selectServiceRoutes } from "./select-service-routes.ts";
+
+const row = (service: string, pattern: string) => ({ config: { service, pattern } });
+
+const PROJECTS = [
+	row("scala-projects", "/:orgId"),
+	row("scala-projects", "/:orgId/kanban"),
+	row("scala-projects", "/sign-in"),
+	row("scala-portal", "/*"),
+	row("scala-quiz", "/"),
+];
+
+describe("selectServiceRoutes", () => {
+	test("a dev lane resolves the rows that name the capability", () => {
+		// The regression this module exists for: before the capability join, a
+		// dev lane matched ZERO rows and served 404 on every path.
+		const got = selectServiceRoutes(PROJECTS, "scala-projects-bun-dev");
+		expect(got.map((r) => r.config.pattern).sort()).toEqual([
+			"/:orgId",
+			"/:orgId/kanban",
+			"/sign-in",
+		]);
+	});
+
+	test("both lanes of one application resolve the same set", () => {
+		const dev = selectServiceRoutes(PROJECTS, "scala-projects-bun-dev");
+		const prodBare = selectServiceRoutes(PROJECTS, "scala-projects");
+		const prodTiered = selectServiceRoutes(PROJECTS, "scala-projects-bun-prod");
+		expect(dev).toEqual(prodBare);
+		expect(dev).toEqual(prodTiered);
+	});
+
+	test("a row naming a deployable form still matches its lane", () => {
+		const rows = [row("scala-roadmap-bun-dev", "/")];
+		expect(selectServiceRoutes(rows, "scala-roadmap")).toHaveLength(1);
+	});
+
+	test("never returns another service's rows", () => {
+		const got = selectServiceRoutes(PROJECTS, "scala-projects-bun-dev");
+		expect(got.every((r) => r.config.service === "scala-projects")).toBe(true);
+	});
+
+	test("orders literal before param before wildcard", () => {
+		const rows = [
+			row("scala-portal", "/*"),
+			row("scala-portal", "/:orgId"),
+			row("scala-portal", "/sign-in"),
+		];
+		expect(
+			selectServiceRoutes(rows, "scala-portal").map((r) => r.config.pattern),
+		).toEqual(["/sign-in", "/:orgId", "/*"]);
+	});
+
+	test("an unknown service resolves nothing", () => {
+		expect(selectServiceRoutes(PROJECTS, "scala-nonexistent-bun-dev")).toEqual([]);
+	});
+});

package/src/select-service-routes.ts

@@ -0,0 +1,66 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Selecting and ordering the `page_route` rows one service serves.
+ *
+ * Two decisions live here, both about WHICH rows and IN WHAT ORDER — never
+ * about what a route does once matched:
+ *
+ * 1. SELECTION joins on the CAPABILITY, never on the deployable name. A
+ *    service arrives under its LANE identity (`scala-projects-bun-dev` in
+ *    dev, `scala-projects` in prod), while a page_route row names the
+ *    APPLICATION and there is ONE row for both lanes. Raw string equality
+ *    therefore matched at most one lane, silently — see `./capability-slug.ts`
+ *    for the measured incident.
+ *
+ * 2. ORDERING puts specific patterns before parameterised and wildcard ones,
+ *    because Hono matches in REGISTRATION order.
+ */
+
+import { toCapabilitySlug } from "./capability-slug.ts";
+
+/** The shape this module needs from a loaded page_route row. */
+export interface SelectableRoute {
+	config: { pattern: string; service: string };
+}
+
+/**
+ * Specificity rank for registration order. Hono matches by registration
+ * order, so `/*` (the portal catchall) registered before `/sign-in` would
+ * swallow the sign-in page and render it inside the PortalTemplate instead
+ * of the standalone PublicTemplate shell.
+ */
+function comparePatternSpecificity(a: string, b: string): number {
+	// Wildcard `/*` goes last.
+	if (a === "/*") return 1;
+	if (b === "/*") return -1;
+	// Param routes `/:param` sort after literal routes.
+	const aIsLiteral = !a.includes(":") && !a.includes("*");
+	const bIsLiteral = !b.includes(":") && !b.includes("*");
+	if (aIsLiteral && !bIsLiteral) return -1;
+	if (!aIsLiteral && bIsLiteral) return 1;
+	return 0;
+}
+
+/**
+ * The page_route rows this service serves, in registration order.
+ *
+ * `serviceSlug` is the deployable identity of the calling lane; both sides
+ * of the join normalize through `toCapabilitySlug`, so a row may name either
+ * the capability or a deployable form and both lanes resolve the same set.
+ */
+export function selectServiceRoutes<T extends SelectableRoute>(
+	allRoutes: readonly T[],
+	serviceSlug: string,
+): T[] {
+	const capability = toCapabilitySlug(serviceSlug);
+	const serviceRoutes = allRoutes.filter(
+		(r) => toCapabilitySlug(r.config.service) === capability,
+	);
+	serviceRoutes.sort((a, b) =>
+		comparePatternSpecificity(a.config.pattern, b.config.pattern),
+	);
+	return serviceRoutes;
+}