@teamscala/service-boot 0.23.500 → 0.23.502

package/package.json

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

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/content-gate/access.ts

@@ -37,14 +37,27 @@ export async function attachContentGateAccess(
 		let resourceId = "";
 		let email = "";
 		let name = "";
+		let phone = "";
 		let bodyFailed = false;
+		// The resource id may ride on the URL instead of the body. A gate whose
+		// form is COMPOSED FROM BLOCKS has no place to put a hidden field — the
+		// generic submit action collects the visible inputs and adds only the
+		// static fields its row declares, and a row is shared by every page so it
+		// cannot carry a per-page id. The gate therefore publishes its own access
+		// URL with the id already on it (see quiz-gate onUnauthorized), which
+		// keeps the id single-sourced from the resolved graph. A body field still
+		// wins where one is posted (proposals, agreements, the GPT).
+		const queryResourceId = String(c.req.query(config.recordIdField) ?? "").trim();
 		try {
 			const form = await c.req.parseBody();
-			resourceId = String(form[config.recordIdField] ?? "").trim();
+			resourceId = String(form[config.recordIdField] ?? "").trim() || queryResourceId;
 			email = String(form.email ?? "").trim().toLowerCase();
 			// Optional captured display name (open-capture gates carry it in the
 			// token; allow-list gates ignore it via signToken).
 			name = String(form.name ?? "").trim();
+			// Captured alongside the email by an open-capture gate's composed
+			// form. It rides in the signed token rather than any client store.
+			phone = String(form.phone ?? "").trim();
 		} catch (error) {
 			log.warn(`[content-gate:${config.cookieName}] body parse failed — redirecting back: ${String(error)}`);
 			bodyFailed = true;
@@ -75,7 +88,13 @@ export async function attachContentGateAccess(
 			return c.redirect(`${back}${sep}gate_error=1`, 302);
 		}
 
-		const token = config.signToken(resourceId, email, Date.now(), name || undefined);
+		const token = config.signToken(
+			resourceId,
+			email,
+			Date.now(),
+			name || undefined,
+			phone || undefined,
+		);
 		if (token) {
 			const maxAge = Math.floor(config.ttlMs / 1000);
 			c.header(

package/src/content-gate/catalog.ts

@@ -58,6 +58,7 @@ import type { AccessConfig, ContentGateConfig } from "./config-types.ts";
 import { agreementAccessConfig, agreementGateConfig } from "../agreement-gate.ts";
 import { gptAccessConfig, gptGateConfig } from "../gpt-gate.ts";
 import { proposalAccessConfig, proposalGateConfig } from "../proposal-gate.ts";
+import { quizAccessConfig, quizGateConfig } from "../quiz-gate.ts";
 
 /** One gated content type: its SSR gate and its public access endpoint. */
 export interface ContentGateEntry {
@@ -71,6 +72,7 @@ export const CONTENT_GATES: readonly ContentGateEntry[] = [
 	{ slug: "proposal", gate: proposalGateConfig, access: proposalAccessConfig },
 	{ slug: "agreement", gate: agreementGateConfig, access: agreementAccessConfig },
 	{ slug: "gpt", gate: gptGateConfig, access: gptAccessConfig },
+	{ slug: "quiz", gate: quizGateConfig, access: quizAccessConfig },
 ];
 
 export function withholdsContent(entry: ContentGateEntry): boolean {

package/src/content-gate/config-types.ts

@@ -35,7 +35,7 @@ export interface ContentGateConfig {
 		token: string | undefined,
 		resourceId: string,
 		nowMs: number,
-	): { email: string; name?: string } | null;
+	): { email: string; name?: string; phone?: string } | null;
 	/**
 	 * BAKED-IN unified auth. When a gate provides this resolver, the engine
 	 * AUTOMATICALLY releases a logged-in viewer whose session email is in the
@@ -64,7 +64,7 @@ export interface ContentGateConfig {
 	onAuthorized(
 		resolved: Resolved,
 		resourceId: string,
-		identity: { email: string; name?: string },
+		identity: { email: string; name?: string; phone?: string },
 	): void | Promise<void>;
 	/** Withhold content (strip/inject the gate) — token absent/invalid. Async-
 	 *  capable so a gate can load its display/behaviour settings from a registry
@@ -96,13 +96,15 @@ export interface AccessConfig {
 	resolveAuthorizedEmails(resourceId: string): Promise<Set<string>>;
 	/**
 	 * Mint the access token for a matched email (token-agnostic per gate).
-	 * `name` is the optional captured display name (open-capture gates carry it
-	 * in the token; allow-list gates ignore it).
+	 * `name` and `phone` are the optional captured identity (open-capture gates
+	 * carry them in the token; allow-list gates ignore them). They exist so a
+	 * capture gate needs no browser storage to remember who this is.
 	 */
 	signToken(
 		resourceId: string,
 		email: string,
 		nowMs: number,
 		name?: string,
+		phone?: string,
 	): string | null;
 }

package/src/content-gate/token.ts

@@ -9,7 +9,9 @@
  * the only thing that releases the content into the SSR, so without it a gated
  * page is never readable/scrapable by a link holder.
  *
- * HMAC-SHA256 (Bun-native) over {c:cookieName, r:resourceId, e:email, x:exp}.
+ * HMAC-SHA256 (Bun-native) over {c:cookieName, r:resourceId, e:email, x:exp},
+ * plus the optional captured identity a lead-capture gate carries (n:name,
+ * p:phone) so a returning visitor is fully known at SSR with NO client storage.
  * `cookieName` is bound INTO the payload so a token minted for one gate
  * (e.g. ag_token) can never satisfy another gate's check (e.g. prop_token).
  *
@@ -59,10 +61,17 @@ export function signAccessToken(
 	 * (proposals/agreements) omit it.
 	 */
 	name?: string,
+	/**
+	 * Optional captured phone, same reasoning as `name`. It exists so a capture
+	 * gate needs NO browser storage to remember it: the operator's ruling is
+	 * that identity lives in the database and the request, never in
+	 * localStorage.
+	 */
+	phone?: string,
 ): string | null {
 	const key = secret();
 	if (!key) return null;
-	const payload: { c: string; r: string; e: string; x: number; n?: string } = {
+	const payload: { c: string; r: string; e: string; x: number; n?: string; p?: string } = {
 		c: cookieName,
 		r: resourceId,
 		e: email.trim().toLowerCase(),
@@ -70,6 +79,8 @@ export function signAccessToken(
 	};
 	const trimmedName = name?.trim();
 	if (trimmedName) payload.n = trimmedName;
+	const trimmedPhone = phone?.trim();
+	if (trimmedPhone) payload.p = trimmedPhone;
 	const payloadB64 = Buffer.from(JSON.stringify(payload)).toString("base64url");
 	return `${payloadB64}.${hmac(payloadB64, key)}`;
 }
@@ -110,7 +121,7 @@ export function verifyAccessToken(
 }
 
 /**
- * Like `verifyAccessToken` but returns the full verified identity ({email, name})
+ * Like `verifyAccessToken` but returns the full verified identity ({email, name, phone})
  * so a gate that carries a display name in the token (the public GPT lead-capture
  * gate) can seed the visitor's name — not just the email — at SSR. Same
  * signature/expiry/gate-binding checks; null on any failure.
@@ -120,7 +131,7 @@ export function verifyAccessTokenIdentity(
 	cookieName: string,
 	resourceId: string,
 	nowMs: number,
-): { email: string; name?: string } | null {
+): { email: string; name?: string; phone?: string } | null {
 	if (!token) return null;
 	const key = secret();
 	if (!key) return null;
@@ -136,12 +147,17 @@ export function verifyAccessTokenIdentity(
 			e?: string;
 			x?: number;
 			n?: string;
+			p?: string;
 		};
 		if (p.c !== cookieName) return null;
 		if (p.r !== resourceId) return null;
 		if (typeof p.x !== "number" || p.x < nowMs) return null;
 		if (typeof p.e !== "string") return null;
-		return { email: p.e, name: typeof p.n === "string" ? p.n : undefined };
+		return {
+			email: p.e,
+			name: typeof p.n === "string" ? p.n : undefined,
+			phone: typeof p.p === "string" ? p.p : undefined,
+		};
 	} catch {
 		return null;
 	}

package/src/gate-ttls.ts

@@ -4,7 +4,7 @@
  * @edit edit directly
  *
  * Cached readers for the content-gate access-token TTL config rows
- * (agreement-gate / proposal-gate / gpt-gate). initGateTtls() runs once at boot
+ * (agreement-gate / proposal-gate / gpt-gate / quiz-gate). initGateTtls() runs once at boot
  * (two-phase-boot, before the gates mount) to populate the cache from the
  * registry rows; the sync getters (agTtlMs/propTtlMs/gptTtlMs) return the
  * cached value — or the former hardcoded default before init / on row-miss — so
@@ -20,10 +20,14 @@ import * as v from "valibot";
 const DEFAULT_AG_TTL_MS = 30 * 60 * 1000;
 const DEFAULT_PROP_TTL_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_GPT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+// A quiz visitor returns to finish or to re-read their result over days, so the
+// identity cookie outlives one sitting — same lead-capture shape as the GPT.
+const DEFAULT_QUIZ_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 
 let _agTtlMs = DEFAULT_AG_TTL_MS;
 let _propTtlMs = DEFAULT_PROP_TTL_MS;
 let _gptTtlMs = DEFAULT_GPT_TTL_MS;
+let _quizTtlMs = DEFAULT_QUIZ_TTL_MS;
 let _initialized = false;
 
 /** Populate the TTL cache from the registry rows. Idempotent; keeps defaults on
@@ -32,14 +36,16 @@ export async function initGateTtls(): Promise<void> {
 	if (_initialized) return;
 	_initialized = true;
 	try {
-		const [ag, prop, gpt] = await Promise.all([
+		const [ag, prop, gpt, quiz] = await Promise.all([
 			loadRegistryConfig("config", "agreement-gate", v.looseObject({})),
 			loadRegistryConfig("config", "proposal-gate", v.looseObject({})),
 			loadRegistryConfig("config", "gpt-gate", v.looseObject({})),
+			loadRegistryConfig("config", "quiz-gate", v.looseObject({})),
 		]);
 		if (typeof ag?.ag_ttl_ms === "number") _agTtlMs = ag.ag_ttl_ms;
 		if (typeof prop?.prop_ttl_ms === "number") _propTtlMs = prop.prop_ttl_ms;
 		if (typeof gpt?.gpt_ttl_ms === "number") _gptTtlMs = gpt.gpt_ttl_ms;
+		if (typeof quiz?.quiz_ttl_ms === "number") _quizTtlMs = quiz.quiz_ttl_ms;
 	} catch {
 		// keep defaults
 	}
@@ -54,3 +60,6 @@ export function propTtlMs(): number {
 export function gptTtlMs(): number {
 	return _gptTtlMs;
 }
+export function quizTtlMs(): number {
+	return _quizTtlMs;
+}

package/src/quiz-gate.ts

@@ -0,0 +1,87 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The PUBLIC QUIZ identity gate, expressed as config for the content-gate
+ * primitive. Like the GPT gate this is lead capture, not access control: every
+ * email is a valid visitor. Its job is to make the visitor KNOWN AT SSR so the
+ * page's identity blocks hide themselves and the quiz blocks reveal themselves
+ * — by block condition on `initialVisitor`, never by a component deciding which
+ * screen to render.
+ *
+ * That is the whole point of this file existing. The quiz identity form used to
+ * be a composite React component that hand-assembled a logo, a heading, three
+ * inputs and a button, and then branched in TypeScript on whether a visitor was
+ * known. Every one of those pieces is already a Puck block, and the branch is
+ * already expressible as a block condition — what was missing was only the
+ * server half: something to turn a submitted email into a visitor the next
+ * render can see. This is that half, and it is 60 lines of config because the
+ * engine (content-gate/gate.ts + access.ts) already does the work.
+ *
+ * Flow: the composed form POSTs {quizId, name, email, phone} to
+ * /api/quiz-access (openCapture → any email matches); the access endpoint signs
+ * a `quiz_token` cookie and redirects back. On the next request runContentGate
+ * verifies it for this assessment and seeds resolved.initialVisitor.
+ */
+
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+import { signAccessToken, verifyAccessTokenIdentity } from "./content-gate/token.ts";
+import { quizTtlMs } from "./gate-ttls.ts";
+
+const QUIZ_COOKIE = "quiz_token";
+const QUIZ_ACCESS_PATH = "/api/quiz-access";
+
+/** The assessment this page is for, from the quiz-with-brand loader's graph. */
+function quizId(resolved: Record<string, unknown>): string {
+	const quiz = resolved.quiz as { id?: unknown } | null | undefined;
+	return typeof quiz?.id === "string" ? quiz.id : "";
+}
+
+export const quizGateConfig: ContentGateConfig = {
+	cookieName: QUIZ_COOKIE,
+	getResourceId(resolved) {
+		// No quiz in the graph → not a quiz page → the engine no-ops.
+		return quizId(resolved);
+	},
+	verifyToken(token, resourceId, nowMs) {
+		return verifyAccessTokenIdentity(token, QUIZ_COOKIE, resourceId, nowMs);
+	},
+	onAuthorized(resolved, _resourceId, { email, name, phone }) {
+		// The one fact the page's block conditions read. Present → the identity
+		// container hides and the quiz container shows; absent → the reverse.
+		(resolved as {
+			initialVisitor?: { name?: string; email: string; phone?: string };
+		}).initialVisitor = { name, email, phone };
+	},
+	onUnauthorized(resolved, resourceId) {
+		// The endpoint the identity form posts to, PUBLISHED INTO THE PAGE DATA
+		// rather than typed into the page. The assessment id is per-page, so a
+		// static row could not carry it and a literal in the page tree would be
+		// a second copy of the id the URL already states. The submit Button
+		// resolves this by field path (page-data → loaderData), exactly as it
+		// resolves any other live value.
+		(resolved as { quizAccess?: { url: string } }).quizAccess = {
+			url: `${QUIZ_ACCESS_PATH}?quizId=${encodeURIComponent(resourceId)}`,
+		};
+	},
+};
+
+export const quizAccessConfig: AccessConfig = {
+	path: QUIZ_ACCESS_PATH,
+	cookieName: QUIZ_COOKIE,
+	get ttlMs() {
+		return quizTtlMs();
+	},
+	recordIdField: "quizId",
+	// Lead capture: any email identifies a visitor. Nothing is withheld — the
+	// quiz is public, only the answers are attributed.
+	openCapture: true,
+	// Never called under openCapture; present to satisfy the config contract.
+	async resolveAuthorizedEmails() {
+		return new Set<string>();
+	},
+	signToken(resourceId, email, nowMs, name, phone) {
+		return signAccessToken(QUIZ_COOKIE, resourceId, email, nowMs, quizTtlMs(), name, phone);
+	},
+};

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-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;
+}