@teamscala/service-boot 0.23.524 → 0.23.525

package/src/mount-orpc-router.ts

@@ -26,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(/\/+$/, "");
@@ -52,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, {
@@ -67,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(
@@ -91,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"
 		);
@@ -114,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(
@@ -141,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);
 			}
@@ -154,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"),
@@ -186,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,
 			});
@@ -226,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" ||
@@ -260,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}`,
@@ -273,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

@@ -89,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,
@@ -122,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; ` +
@@ -158,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/mutable-app-ref.ts

@@ -7,18 +7,11 @@ 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");
@@ -26,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;

package/src/orpc-contract-rows.json

@@ -120,6 +120,295 @@
       "package": "@teamscala/service-boot",
       "suite_type": "function_call",
       "slug": "boot:openapi-contract-refuses-when-no-key-is-configured"
+    },
+    {
+      "args": [
+        {},
+        "quiz_token=good; quiz_token_entered=1",
+        1730000000000,
+        {
+          "cookieName": "quiz_token",
+          "verifyToken": {
+            "$fn": {
+              "returns": {
+                "name": "V",
+                "email": "v@example.com"
+              }
+            }
+          },
+          "onAuthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "getResourceId": {
+            "$fn": {
+              "returns": "res-1"
+            }
+          },
+          "onUnauthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "entryCookieName": "quiz_token_entered"
+        }
+      ],
+      "note": "Converts gate-entry-marker.test.ts case 3, including the measured first-shipped-version failure (the clears read after the run() scope saw nothing and left the marker in the browser, measured live 2026-09-14): recording is asserted from the recorded call itself, which a post-scope read cannot fake.",
+      "label": "an opting gate with token AND marker authorizes and RECORDS the marker for clearing — one view, then the gate returns",
+      "expect": {
+        "email": "v@example.com",
+        "applies": true,
+        "authorized": true
+      },
+      "export": "runContentGate",
+      "module": "src/content-gate/gate.ts",
+      "package": "@teamscala/service-boot",
+      "fixtures": {
+        "stubs": [
+          {
+            "export": "recordGateEntryClear",
+            "module": "./gate-entry-clears.ts",
+            "record": "clears",
+            "returns": null
+          }
+        ]
+      },
+      "outcomes": {
+        "clears": [
+          {
+            "count": 1
+          },
+          {
+            "equals": [
+              {
+                "args": [
+                  "quiz_token_entered"
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      "suite_type": "function_call",
+      "slug": "gate-entry-marker:marker-plus-token-authorizes-and-records-clear"
+    },
+    {
+      "args": [
+        {},
+        "quiz_token=bad; quiz_token_entered=1",
+        1730000000000,
+        {
+          "cookieName": "quiz_token",
+          "verifyToken": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "onAuthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "getResourceId": {
+            "$fn": {
+              "returns": "res-1"
+            }
+          },
+          "onUnauthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "entryCookieName": "quiz_token_entered"
+        }
+      ],
+      "note": "Converts gate-entry-marker.test.ts case 4.",
+      "label": "marker present but token invalid stays unauthorized and records no clear",
+      "expect": {
+        "applies": true,
+        "authorized": false
+      },
+      "export": "runContentGate",
+      "module": "src/content-gate/gate.ts",
+      "package": "@teamscala/service-boot",
+      "fixtures": {
+        "stubs": [
+          {
+            "export": "recordGateEntryClear",
+            "module": "./gate-entry-clears.ts",
+            "record": "clears",
+            "returns": null
+          }
+        ]
+      },
+      "outcomes": {
+        "clears": [
+          {
+            "count": 0
+          }
+        ]
+      },
+      "suite_type": "function_call",
+      "slug": "gate-entry-marker:marker-without-valid-token-records-no-clear"
+    },
+    {
+      "args": [
+        {},
+        "quiz_token=good",
+        1730000000000,
+        {
+          "cookieName": "quiz_token",
+          "verifyToken": {
+            "$fn": {
+              "returns": {
+                "name": "V",
+                "email": "v@example.com"
+              }
+            }
+          },
+          "onAuthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "getResourceId": {
+            "$fn": {
+              "returns": "res-1"
+            }
+          },
+          "onUnauthorized": {
+            "$fn": {
+              "returns": null
+            }
+          }
+        }
+      ],
+      "note": "Converts the hand-written gate-entry-marker.test.ts case 1: the entry marker is opt-in, so every non-opting service behaves exactly as before. Converted 2026-10-07 by the tests-out conversion.",
+      "label": "a gate that does NOT declare an entry marker authorizes on any load and records nothing for clearing",
+      "expect": {
+        "email": "v@example.com",
+        "applies": true,
+        "authorized": true
+      },
+      "export": "runContentGate",
+      "module": "src/content-gate/gate.ts",
+      "package": "@teamscala/service-boot",
+      "fixtures": {
+        "stubs": [
+          {
+            "export": "recordGateEntryClear",
+            "module": "./gate-entry-clears.ts",
+            "record": "clears",
+            "returns": null
+          }
+        ]
+      },
+      "outcomes": {
+        "clears": [
+          {
+            "count": 0
+          }
+        ]
+      },
+      "suite_type": "function_call",
+      "slug": "gate-entry-marker:non-opting-authorizes-any-load-records-nothing"
+    },
+    {
+      "args": [
+        {},
+        "quiz_token=good",
+        1730000000000,
+        {
+          "cookieName": "quiz_token",
+          "verifyToken": {
+            "$fn": {
+              "returns": {
+                "name": "V",
+                "email": "v@example.com"
+              }
+            }
+          },
+          "onAuthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "getResourceId": {
+            "$fn": {
+              "returns": "res-1"
+            }
+          },
+          "onUnauthorized": {
+            "$fn": {
+              "returns": null
+            }
+          },
+          "entryCookieName": "quiz_token_entered"
+        }
+      ],
+      "note": "Converts gate-entry-marker.test.ts case 2: the marker, not the token alone, is what skips the gate — the mechanism measured live 2026-09-14 when the quiz_token cookie alone let a refresh past the identity gate.",
+      "label": "an opting gate authorizes only the request carrying the marker — a token WITHOUT it is unauthorized, so a refresh shows the gate",
+      "expect": {
+        "applies": true,
+        "authorized": false
+      },
+      "export": "runContentGate",
+      "module": "src/content-gate/gate.ts",
+      "package": "@teamscala/service-boot",
+      "fixtures": {
+        "stubs": [
+          {
+            "export": "recordGateEntryClear",
+            "module": "./gate-entry-clears.ts",
+            "record": "clears",
+            "returns": null
+          }
+        ]
+      },
+      "outcomes": {
+        "clears": [
+          {
+            "count": 0
+          }
+        ]
+      },
+      "suite_type": "function_call",
+      "slug": "gate-entry-marker:opting-gate-without-marker-is-unauthorized"
+    },
+    {
+      "args": [],
+      "note": "Converts the pairing half of gate-entry-marker.test.ts: gate and access endpoint must declare the SAME marker name, or the endpoint's redirect carries a cookie the gate never reads and the one-view never happens. Converted 2026-10-07.",
+      "label": "the quiz access endpoint opts into the SAME entry marker as the gate",
+      "expect": {
+        "export_shape": {
+          "member_equals": {
+            "entryCookieName": "quiz_token_entered"
+          }
+        }
+      },
+      "export": "quizAccessConfig",
+      "module": "src/quiz-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "quiz-gate:access-endpoint-shares-the-entry-marker"
+    },
+    {
+      "args": [],
+      "note": "Converts the pairing half of gate-entry-marker.test.ts: the quiz SSR gate carries the marker name, so a refresh returns to the identity gate (operator ruling 2026-09-14). Converted 2026-10-07.",
+      "label": "the quiz gate opts into the one-view entry marker",
+      "expect": {
+        "export_shape": {
+          "member_equals": {
+            "entryCookieName": "quiz_token_entered"
+          }
+        }
+      },
+      "export": "quizGateConfig",
+      "module": "src/quiz-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "quiz-gate:gate-declares-the-one-view-entry-marker"
     }
   ]
 }

package/src/orpc-openapi-document.ts

@@ -3,12 +3,6 @@
  * @status handwritten
  */
 
-/**
- * Both fallbacks are read through FALSYNESS, not `??`: a header that is
- * present but empty named nothing, and `"" ?? "http"` would splice an
- * empty scheme into the URL as `://host` — a document that serves and
- * cannot be called from (caught by the row passing empty positions).
- */
 import type { OpenApiDocumentOptions } from "@teamscala/orpc/openapi";
 
 const FALLBACK_HOST = "localhost";

package/src/orpc-openapi-gate.ts

@@ -3,23 +3,13 @@
  * @status handwritten
  */
 
-/**
- * The four request facts the gate reads, all optional: a fact the caller
- * did not send is absent, never a value to trust. Truthiness reads absence
- * and null identically, so a header is an assertion, not a hint.
- */
 export interface OpenApiContractRequest {
-	/** The raw `authorization` header, absent when the caller sent none. */
 	authorization?: string | null;
-	/** The configured `SCALA_DEV_KEY`, absent when the service has none. */
 	key?: string | null;
-	/** `x-forwarded-proto`. Its presence means the request was proxied. */
 	forwardedProto?: string | null;
-	/** `x-forwarded-for`. Same meaning, checked so neither alone is load-bearing. */
 	forwardedFor?: string | null;
 }
 
-/** True only for an unproxied request presenting exactly the configured key. */
 export function openApiContractAuthorised(request: OpenApiContractRequest): boolean {
 	if (!request.key) return false;
 	if (request.forwardedProto || request.forwardedFor) return false;

package/src/pg-boss-handler-registry.ts

@@ -7,21 +7,9 @@ import { createRegistry } from "@teamscala/generic-registry/create-registry";
 
 export type PgBossJobHandler = (ctx: {
 	config: ScheduledJobConfig;
-	/** Per-job data payload from a one-shot `boss.send()` — absent for scheduled jobs. */
 	jobData?: unknown;
 }) => Promise<unknown> | unknown;
 
 export const pgBossHandlerRegistry = createRegistry<PgBossJobHandler>(
 	"pg-boss-handlers",
 );
-
-/**
- * Register a handler for a `scheduled_job.handler_slug`. Idempotent on re-import
- * (createRegistry.register overwrites silently — last registration wins).
- */
-export function registerScheduledJobHandler(
-	slug: string,
-	handler: PgBossJobHandler,
-): void {
-	pgBossHandlerRegistry.register(slug, handler);
-}