@teamscala/service-boot 0.23.523 → 0.23.525

package/src/register-registry-page-route/warn-uncovered-blocks.ts

@@ -1,28 +1,11 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Block-coverage guard (protective-layers-fail-explicitly) for registered
- * page routes.
- *
- * Split out of register-registry-page-route.ts (924 lines) — byte-for-byte
- * move; only the import paths adjusted.
  */
 
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { RendererComponentEntry } from "../types.ts";
 
-/**
- * A page that renders a block whose component is NOT registered — because
- * its package is missing from service_install.config.block_packages —
- * silently renders BLANK. That is the exact failure behind the 2026-06-04
- * scala-sign regression (sign-in-block dropped from block_packages → the
- * gate + signature fields vanished) which left only a benign boot WARN.
- * This turns that silent blank into a loud, GlitchTip-visible ERROR naming
- * the page + block, throttled to once per (service, block type) so a hot
- * path can never spam it.
- */
 const uncoveredBlocksLogged = new Set<string>();
 
 function collectBlockTypes(node: unknown, out: Set<string>): void {

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

@@ -1,23 +1,6 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Reads `page_route` registry rows for the current service slug and registers
- * Hono routes that resolve data via `resource_loader` graph-based sources.
- *
- * Every page_route uses pattern `/:id` and every resource_loader uses a
- * `sources[]` dependency graph. When header/footer sources are present in
- * the resolved graph, the output includes a `regions` array for shell rendering.
- * Otherwise it produces single-page puckData.
- *
- * This module is the ROUTE-REGISTRATION unit: row loading, specificity
- * ordering, handler binding. The per-request loadData pipeline segments live
- * as siblings under ./register-registry-page-route/ (graph-cache,
- * resolve-request-graph, stamp-session-context, run-content-gates,
- * apply-page-branding, resolve-panel-page, warn-uncovered-blocks,
- * resolve-page-data, meta-title, ai-chat-prefetch, captured-loader-config,
- * proposal-*) — split when the parent held them all at 924 lines.
  */
 
 import type { InferOutput } from "valibot";
@@ -139,22 +122,11 @@ export async function registerRegistryPageRoute(
 	for (const routeRow of serviceRoutes) {
 		const routeConfig = routeRow.config;
 		const pattern = routeConfig.pattern;
-		// loader_slug is a page_route runtime value and resource_loader is runtime
-		// data: a row created after this build is exactly the live-edit case this
-		// module serves, so the generated slug union (a build-time snapshot) can
-		// only be asserted, never enforced, here. An unknown slug still fails
-		// closed below (RegistryConfigMissingError skips the route).
 		const loaderSlug = routeConfig.loader_slug as ResourceLoaderKey;
 		const routeProviders = routeConfig.providers ?? baseProviders;
 
 		let loaderConfig: LoaderConfig | null = null;
 		try {
-			// Boot-time warm + validate: a missing row skips the route (warn),
-			// an invalid row fails closed. resource_loader is NOT on the
-			// deploy-time bake list (constitution installer-and-runtime) — it
-			// is re-read per request via readLiveLoaderConfig below — so this
-			// boot read exists ONLY to catch a misconfigured row early, never
-			// as the source of truth for live rendering.
 			loaderConfig = await loadRegistryConfig(
 				"resource_loader",
 				loaderSlug,
@@ -173,22 +145,12 @@ export async function registerRegistryPageRoute(
 			throw err;
 		}
 
-		// Gate for the static-shell graph cache (see module header).
 		const isStaticShell =
 			!routeConfig.resource_type &&
 			!pattern.includes(":") &&
 			!pattern.includes("*");
 
 		const loadData = async (request: Request) => {
-			// resource_loader is runtime data, not deploy-time baked. Re-read it
-			// per request — loadRegistryConfig's SWR cache makes the fresh-window
-			// hit a memory read, not a DB round trip. Throws into the branded
-			// error path on a vanished or invalid row: the boot-time snapshot
-			// must NEVER silently outlive the row it captured. This is the fix
-			// for the loader-row-edits-look-like-they-don't-work defect (every
-			// edit used to need a service restart; the sign-page-with-brand
-			// `agreement` source added at 22:16 still hadn't reached
-			// __PAGE_DATA__.loaderData at 22:29 — 13 minutes, and never).
 			const liveLoaderConfig = await readLiveLoaderConfig(loaderSlug);
 			const url = new URL(request.url);
 			const params = extractUrlParams(pattern, url.pathname);
@@ -202,10 +164,6 @@ export async function registerRegistryPageRoute(
 				params,
 				isStaticShell,
 				serviceSlug,
-				// Folds the live config into the per-route graphKey so a row edit
-				// invalidates the cached graph immediately (the graph is a
-				// function of the config; without this the SWR graph cache
-				// would still hold the old shape until its fresh window lapsed).
 				configFingerprint: fingerprintLoaderConfig(liveLoaderConfig),
 			});
 			const { sessionUserId, sessionOrgId } = await stampSessionContext(
@@ -220,8 +178,6 @@ export async function registerRegistryPageRoute(
 				resolved,
 				gateCookie,
 				Date.now(),
-				routeConfig.assistant,
-				regionSlots,
 			);
 			const meta = buildMetaFromContext(routeConfig.meta_context, resolved);
 			await applySignInBrandOverride(resolved, request);
@@ -233,13 +189,6 @@ export async function registerRegistryPageRoute(
 		) {
 			meta.title = pageMetaTitle.trim();
 		}
-		// Org-prefixed page titles (feature flag page-title-org-prefix, read
-		// LIVE per request — feature flags are never cached). The title prefix
-		// is the OWNING ORG'S name, never the internal website label
-		// ("Public Pages: <subject>" on a client-facing document was the
-		// defect; operator ruling 2026-08-17). Absent or unreadable flag ⇒
-		// legacy <website.name>: <subject> derivation — the switch fails toward
-		// the pre-flag behaviour, and flipping it back is one registry edit.
 		let orgTitlePrefix = false;
 		try {
 			orgTitlePrefix = (
@@ -250,14 +199,8 @@ export async function registerRegistryPageRoute(
 				)
 			).enabled;
 		} catch {
-			// Flag row absent — legacy derivation.
 		}
 			const themeParam = url.searchParams.get("theme");
-			// ?theme is the EMBED override — only honor it when this page is
-			// actually framed (a form/quiz in a GPT tool panel, sec-fetch-dest:
-			// iframe). A DIRECT visit carrying ?theme= (e.g. copied from a GPT
-			// embed URL) must NOT override the org's DB theme — what the visitor
-			// sees is org-driven, never URL-driven.
 			const isFramedEmbed =
 				request.headers.get("sec-fetch-dest") === "iframe";
 			const themeOverride =
@@ -274,12 +217,6 @@ export async function registerRegistryPageRoute(
 				themeOverride,
 				orgTitlePrefix,
 			);
-			// The matched route params (extractUrlParams + host/path) ride the
-			// per-request pageData so the SSR resolve ctx can scope PUBLIC
-			// block data per request — data_source loaders read ctx.pathParams
-			// (query-data-source); without them a public table would return
-			// every person's rows. Attached AFTER the graph cache (per-request,
-			// never cached with the graph).
 			(pageData as Record<string, unknown>).pathParams = params;
 			const panelSlug = new URL(request.url).searchParams.get("panel");
 			await attachPanelPage(pageData as Record<string, unknown>, panelSlug);
@@ -301,39 +238,22 @@ export async function registerRegistryPageRoute(
 			await applyBrandOrgPath(
 				pageData as Record<string, unknown>,
 				resolved,
-				// brand_org_path is the row schema's own field now — the derived
-				// type sees it, so the narrowing cast the mirror needed is gone.
 				routeConfig.brand_org_path,
 				params,
 				serviceSlug,
 			);
 			warnUncoveredBlocks(pageData, components, serviceSlug, params.path, log);
-			// Detached (NOT awaited into the response). prefetchAiChatSession -> createOrRestore is DB-heavy (~1.1s), per-user, and uncached, and was
-			// awaited on EVERY loadData — the dominant board loadMs cost (confirmed
-			// aiChatPrefetch=1145ms = the full loadMs). Fire it in the background so
-			// it still warms the server-side session (users who open chat find it
-			// warm via their live fetch) without blocking the page response. The SSR
-			// chat seed (pageData.aiChatSession) is sacrificed — chat opens with a
-			// live fetch instead of SSR-instant — the right trade: most loads never
-			// open chat, so eager-awaited prefetch was the waste. orgId is the
-			// URL-derived org (resolveAiOrgId) — see prefetch-org-id.ts for why
-			// segment 1 is preferred over segment 0.
 			const aiOrgId = resolveAiOrgId(new URL(request.url).pathname);
 			void prefetchAiChatSession(resolved, sessionUserId, aiOrgId).catch((err) =>
 				log.warn(
 					`[scala-install:${serviceSlug}] background ai-chat prefetch failed: ${err instanceof Error ? err.message : err}`,
 				),
 			);
-			// Proposal pages: resolve the {{approvalEmail}} button token to the
-			// org's registered company email (creator email as fallback).
 			if (resolved.proposal) {
 				await applyApprovalEmailToken(
 					pageData as Record<string, unknown>,
 					resolved.proposal as { created_by?: string } | undefined,
 				);
-				// Stash the partner logo from the partnerOrg loader source (CRM record
-				// loaded by partner_id) onto pageData.partnerLogo — header fills
-				// automatically, no inline body-Hero prop needed.
 				applyPartnerBrand(
 					pageData as Record<string, unknown>,
 					resolved.partnerOrg as
@@ -341,10 +261,6 @@ export async function registerRegistryPageRoute(
 						| undefined
 						| null,
 				);
-				// Auto-resolve the client's company logo from the clientOrg loader
-				// source (contact → company → crm_organisations.logo_url). Only
-				// injects when the Hero's clientLogo prop is empty — a manually set
-				// logo always wins.
 				applyClientLogo(
 					pageData as Record<string, unknown>,
 					resolved.clientOrg as
@@ -370,10 +286,6 @@ export async function registerRegistryPageRoute(
 			providers: routeProviders,
 			renderMode: routeRenderMode,
 			loadData: loadData as never,
-			// The portal home redirect follows the DECLARED portal_scoped service
-		// fact (see RegistryRouteArgs.portalScoped) — a signed-in user at "/" of
-		// an org-scoped portal belongs at /<websiteId>/<orgId>/dashboard; a
-		// flat-path service (the fleet dashboard) serves its real page at "/".
 			portalHomeRedirect: portalScoped,
 			serviceSlug,
 		});
@@ -391,10 +303,6 @@ export async function registerRegistryPageRoute(
 		});
 
 		registeredPatterns.push(pattern);
-		// Boot-validated snapshot (the LIVE read is per request — see
-		// readLiveLoaderConfig); name the shape so a misconfigured row is
-		// visible at boot, and note the live contract so "my loader edit
-		// didn't take effect" routes to the graph SWR window, not a restart.
 		log.info(
 			`[scala-install:${serviceSlug}] registered registry page route "${pattern}" → resource_loader "${loaderSlug}" (boot-validated: ${describeCapturedLoaderConfig(loaderConfig)}; re-read live per request)`,
 		);

package/src/register-static-assets.ts

@@ -1,13 +1,6 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Routes every service exposes regardless of registry config: /health
- * (liveness probe), /favicon.svg (default brand mark), /api/assets/*
- * (S3 asset proxy), and /assets/* (client bundle + stylesheet produced
- * by build-client-assets.ts into dist/client/, served identically in
- * dev and prod per scala-os/ui.md `bun-build-only`).
  */
 
 import { join } from "node:path";
@@ -21,10 +14,6 @@ import { isLoopbackHost } from "@teamscala/os/observability/loopback-host";
 import { handleAssetProxy } from "./asset-proxy";
 import { resolveBrandFaviconPath, warmBrandFaviconCache } from "./resolve-brand-favicon";
 
-// Served ONLY when the org has no brand favicon, so the correct colour is the
-// platform brand default rather than a literal. This changes the generic
-// fallback mark from indigo to the canonical slate; any org with its own
-// favicon is unaffected (resolveBrandFaviconPath wins before this is reached).
 const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="${FALLBACK_PRIMARY_COLOR}"/><text x="16" y="23" text-anchor="middle" font-size="20" font-family="system-ui" fill="white">S</text></svg>`;
 
 export async function registerStaticAssets(
@@ -32,9 +21,6 @@ export async function registerStaticAssets(
 	serviceSlug: string,
 	brandOrg?: string,
 ): Promise<void> {
-	// Warm the brand-favicon cache at boot — the S3 existence probe is a 6-21s
-	// cold call that otherwise stalls the first /favicon.ico after every
-	// restart. Fire-and-forget; never blocks boot or a request.
 	warmBrandFaviconCache(brandOrg);
 
 	app.get("/health", (c) =>
@@ -45,16 +31,6 @@ export async function registerStaticAssets(
 		}),
 	);
 
-	// Localhost-gated heap-attribution probe — the heapSize-vs-RSS split (JS heap
-	// vs native: OTel/Prisma-engine/buffers/compiled code) plus the top object
-	// types by count. Read-only, no secrets; gated to a localhost Host so it never
-	// answers over the public domain. Registered here (before auth + page routes)
-	// so it is reachable on every service kind, like /health
-	// (`verify-via-127.0.0.1`, sibling of `runtime-metrics-via-railway-cli`).
-	//
-	// The payload shape lives in @teamscala/os so standalone `Bun.serve` daemons
-	// (scala-guard) answer this probe identically — `scala-tools heap <slug>` must
-	// not mean different things depending on which process replied.
 	app.get("/_heap", async (c) => {
 		if (!isLoopbackHost(c.req.header("host"))) return c.json({ error: "localhost only" }, 403);
 		try {
@@ -68,16 +44,6 @@ export async function registerStaticAssets(
 		}
 	});
 
-	// Build-id: the content hash of the CURRENT client bundle, read FRESH from the asset manifest on every call (never a process-pinned copy) so a
-	// post-restart rebuild reports its new id immediately. The client self-heal (page-client/boot/build-self-heal) polls this on tab refocus; if it differs
-	// from the build the tab booted with, a new build shipped and the open tab is
-	// stale → it reloads. no-store HTML + immutable hashed assets already prevent
-	// staleness on every FRESH load; this is what closes the one remaining hole —
-	// a tab left OPEN across a deploy, holding old HTML pinned to old asset
-	// hashes, with nothing telling it to re-fetch (the "my tablet still shows the
-	// old broken page" class). The id derives from hydratePath exactly as the
-	// SSR-stamped window.__SCALA_BUILD__ does (render-page-html), so they can
-	// never structurally disagree and trigger a reload loop.
 	app.get("/api/build-id", async (c) => {
 		const path = join(process.cwd(), "dist", "client", "asset-manifest.json");
 		let build = "dev";
@@ -91,10 +57,6 @@ export async function registerStaticAssets(
 		return c.json({ build }, 200, { "cache-control": "no-store" });
 	});
 
-	// A branded host (service_install.config.brand_org) never serves the
-	// generic platform mark — both favicon paths resolve the owning org's
-	// icon from its asset store; the generic SVG remains only for hosts
-	// with no declared owner (multi-tenant / infra).
 	app.get("/favicon.svg", async (_c) => {
 		const brand = await resolveBrandFaviconPath(brandOrg);
 		if (brand)
@@ -112,18 +74,10 @@ export async function registerStaticAssets(
 
 	app.get("/favicon.ico", async (c) => {
 		const brand = await resolveBrandFaviconPath(brandOrg);
-		// 302 (not 301): the brand asset is row-driven and must stay
-		// re-resolvable — a permanent redirect would pin stale targets in
-		// browser caches, the exact failure this route exists to end.
-		// cache-control lets the browser cache the redirect (5min) so it
-		// doesn't re-hit the origin per page load — mirrors /favicon.svg.
 		c.header("cache-control", "public, max-age=300");
 		return c.redirect(brand ?? "/favicon.svg", 302);
 	});
 
-	// Same-origin S3 asset proxy: /api/assets/<key> → bucket. Public,
-	// immutable cache, no auth. Canonical URL form for every logo, favicon,
-	// avatar, uploaded asset — emitted by toAssetPath() in @teamscala/core-ui/theme.
 	app.get("/api/assets/*", (c) => handleAssetProxy(c.req.raw));
 
 	app.use("/assets/*", etag());
@@ -144,12 +98,6 @@ export async function registerStaticAssets(
 		return c.notFound();
 	});
 
-	// Extension auto-update files (.crx + updates.xml) served from ./ext/.
-	// Chrome's extension updater fetches updates.xml over plain HTTPS with no
-	// auth, so this route is registered before any auth gate and on every UI
-	// service. Files are served with short-lived cache so updates propagate
-	// promptly. The ./ext/ directory is gitignored and populated by the
-	// extension build pipeline.
 	app.get("/ext/*", async (c) => {
 		const filePath = join(
 			process.cwd(),

package/src/register-ws-routes.ts

@@ -1,26 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Registers each `service_install.websocket_routes[]` entry as a Hono WS route.
- * The ORPC WS (`/api/rpc/ws`) is mounted by the canonical primitive
- * `mountOrpcWs` (@teamscala/orpc/ws/server) over the FULLY-COMPOSED app router —
- * this runs AFTER the app router composition, so the eager RPCHandler snapshots every
- * namespace, and any `output: eventIterator(...)` procedure dispatches (rule
- * `orpc-ws-via-mount-orpc-ws`). It is NOT a server_package WsRouteHandler — it
- * is exempt from the legacy invariant below.
- *
- * The legacy `WsRouteHandler` interface (open/message/close on a Bun
- * ServerWebSocket) is preserved by an adapter for already-migrated
- * server_packages (terminal-ws); new WS handlers should use Hono's WSEvents
- * directly.
- *
- * INVARIANT (legacy paths only): every handler registered via
- * mountCtx.registerWsRoute MUST have a matching entry in config.websocket_routes
- * (minus /api/rpc/ws), and vice versa. A mismatch is fatal — the service cannot
- * boot with handlers declared but never wired (silent 404 on upgrade), or routes
- * that point at handlers no server_package registered.
  */
 
 import { getAppRouter } from "@teamscala/orpc/app-router";

package/src/resolve-brand-favicon.ts

@@ -1,19 +1,6 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Host-level brand favicon resolution. A single-brand UI service's host has
- * a KNOWN owner (`service_install.config.brand_org`) — serving the generic
- * platform "S" at the implicit /favicon.ico path there is a defect: browsers
- * and crawlers hit that path directly and their favicon caches are sticky
- * (operator-observed 2026-06-05 on launcha's proposal pages).
- *
- * Resolution is by convention from the org's asset store:
- * `<brand_org>/logos/favicon.png`. Existence is probed once through the
- * in-process asset proxy and cached (positive AND negative) so the favicon
- * route never adds S3 latency per request. No brand_org, or no asset at the
- * convention key → null, and the caller serves the generic fallback.
  */
 
 import { createCache } from "@teamscala/cache/create-cache";
@@ -50,15 +37,6 @@ export async function resolveBrandFaviconPath(
 	});
 }
 
-/**
- * Eagerly resolve + cache the favicon at boot so the FIRST user request never
- * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
- * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
- * store takes 6s locally / up to 21s in prod, and the in-process cache resets
- * on every restart (deploys, dep-sync). Without warming, the first
- * /favicon.ico after each restart stalls for that duration (operator-reported
- * 23s). Fire-and-forget — runs in the background during boot, never blocks.
- */
 export function warmBrandFaviconCache(brandOrg: string | undefined): void {
 	if (!brandOrg) return;
 	void resolveBrandFaviconPath(brandOrg);

package/src/resolve-service-port.ts

@@ -1,63 +1,11 @@
 /**
- * @system service-runtime
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Decides which port a service binds, from the two sources that can claim one:
- * the PORT environment variable and the port the registry declares for that
- * service (`service_routing.local_port` for a backend, `service_install.port`
- * for a UI service).
- *
- * This is the resolver for BOTH kinds. It lives in service-boot rather than
- * service-runtime because the UI branch boots from here and may not import
- * upward; keeping one copy is the point, since the second copy is exactly what
- * went wrong (below).
- *
- * The rule, and why it is not "env always wins":
- *
- * Railway injects PORT and healthchecks that exact port, reporting the service
- * unavailable if it listens elsewhere. So on Railway the injected PORT is
- * authoritative period — a `service_install`/`service_routing` row carries the
- * service's LOCAL dev port (e.g. portal 5200), and on Railway binding that
- * instead of PORT means Railway probes a port nothing listens on and the deploy
- * fails healthcheck. The registry-wins rule below exists to stop LOCAL port
- * collisions (one host, many services); inside a Railway container there are no
- * sibling services to collide with, so PORT must win. `isRailway` is the caller's
- * assertion that it is booting inside Railway (from `RAILWAY_ENVIRONMENT`).
- *
- * Off Railway, a `service_routing`/`service_install` row means this service has
- * a DECLARED port on this host. There, a PORT that disagrees is a polluted launcher environment, never
- * an intention, and obeying it binds someone else's port. That is not a
- * hypothetical: mcp-ai-chat-system booted onto 3021 — session-picker's port —
- * while its own MCP_SERVER_URL still pointed at 8080. Both processes bound 3021,
- * SO_REUSEPORT load-balanced between them, and every symptom appeared somewhere
- * else: a chat loopback that resolved to nothing, tool-description curation
- * failing for every tool and disabling itself via its circuit breaker, RPC calls
- * landing in the wrong service, and 59 restarts. Nothing failed loudly because
- * nothing ever compared the two numbers.
- *
- * So the registry wins wherever it has an opinion, and the disagreement is
- * REPORTED rather than silently resolved — a wrong port that boots cleanly is
- * the expensive shape, because the damage surfaces far from the cause.
- *
- * That reasoning was written for the backend branch and wired only there, so
- * the UI branch kept taking `process.env.PORT` unconditionally — and on
- * 2026-07-31 reproduced the identical incident in the other direction:
- * scala-quiz (kind:ui, declared 5203) inherited a leaked PORT=3021 from the
- * tmux server environment and bound session-picker's port. Half of every RPC
- * to the session daemon was answered by a quiz service with no /rpc routes.
- *
- * A rule enforced on one of two branches is not enforced. Both branches now
- * call this function, and `port-resolution-is-registry-authoritative` fails
- * the push if either stops.
  */
 
 export interface PortResolution {
-	/** The port to bind. */
 	port: number;
-	/** Which source decided it — for the boot log, so the choice is auditable. */
 	source: "env" | "service_routing";
-	/** Set when PORT disagreed with the row; the caller logs it. */
 	conflict?: { envPort: number; declaredPort: number };
 }
 
@@ -65,14 +13,6 @@ function isBindablePort(value: number | undefined): value is number {
 	return value !== undefined && Number.isFinite(value) && value > 0 && value <= 65535;
 }
 
-/**
- * @param envPort   parsed PORT env, or undefined when unset/unparseable
- * @param declaredPort `service_routing.local_port`, or undefined when the
- *                     service has no routing row (the Railway-only case)
- * @param isRailway  true when booting inside Railway (caller derives from
- *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
- *                   regardless of the row, because Railway healthchecks it
- */
 export function resolveServicePort(
 	envPort: number | undefined,
 	declaredPort: number | undefined,

package/src/resolve-theme-mode.ts

@@ -1,32 +1,10 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The ONE theme-mode decider for every page render, across every UI app
- * (portal, proposals, sign, forms, quiz, gpt, public). Every route handler in service-boot
- * resolves light/dark through this single function — never its own inline
- * `(... === "dark" ? "dark" : "light")` chain. That inline form was duplicated
- * across every route branch, so flipping one app's theme required editing
- * every copy (the heavy lifting this removes).
- *
- * Resolution order (first match wins):
- *   1. ?theme=light|dark on the URL — the embed override. Set when a page is
- *      framed inside another shell (a form in a GPT tool panel) so the framed
- *      page matches the host's scheme. Also marks the render `embedded` so the
- *      page can drop its own brand page-surface and render the host's clean
- *      surface.
- *   2. candidates[] — page rootProps.theme, brand theme, website default, in
- *      whatever priority the caller passes them.
- *   3. "light".
- *
- * Pairs with the brand/token decider (resolveBrand → computeThemeVars,
- * `unified-brand-theme`): that owns the SURFACE, this owns the MODE.
  */
 
 export interface ResolvedThemeMode {
 	theme: "light" | "dark";
-	/** True iff the mode came from the ?theme= embed override. */
 	embedded: boolean;
 }
 
@@ -35,15 +13,8 @@ function asMode(value: unknown): "light" | "dark" | undefined {
 }
 
 export function resolveThemeMode(opts: {
-	/** Request URL (or its href) — read for the ?theme= embed override. */
 	url?: URL | string | null;
-	/**
-	 * Explicit embed override, when the caller already extracted ?theme= from
-	 * the URL upstream (e.g. a pure data-shaper that has no Request). Same
-	 * effect and priority as the URL form.
-	 */
 	override?: unknown;
-	/** Theme candidates in priority order: rootTheme, brandTheme, websiteTheme. */
 	candidates?: Array<unknown>;
 }): ResolvedThemeMode {
 	let override = asMode(opts.override);

package/src/resolvers/app-header.ts

@@ -1,27 +1,8 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * app-header.ts — shared application header resolver_fn.
- *
- * Shapes an app's per-row resolver_input into the canonical header-data object
- * the ONE shared header Puck page (`/shared-app-header`) binds through the
- * unified page-data surface (`dataSource:"page-data"` + `fieldPath:"headerData.<key>"`).
- * The loader row owns the mapping (title field path, label/value pairs — the
- * per-app variation); this executor owns the shape and the two coercions the
- * rows cannot express:
- *
- * - `Date` values (Prisma returns Date objects) → ISO strings, so
- *   __PAGE_DATA__ serialises them the same way the client reads them
- *   (server-serializes-client-reads-verbatim).
- * - the literal `"today"` → a noon-UTC ISO instant of the AEST calendar date.
- *   Noon keeps the calendar date stable under every timezone offset, so the
- *   header shows the same day on the server and on any visitor's client —
- *   the deterministic replacement for the old `format:"today"` clock block.
  */
 
-/** AEST calendar date (the operator timezone) as `YYYY-MM-DD`. */
 function aestCalendarDate(now: Date): string {
 	return new Intl.DateTimeFormat("en-CA", {
 		timeZone: "Australia/Sydney",

package/src/resolvers/fetch-org-brand.ts

@@ -1,21 +1,11 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * fetch-org-brand.ts — org brand resolver with page-org-first fallback.
- *
- * Wraps @teamscala/resolver-engine's fetchOrgBrand with the page-org-first
- * fallback (portal-branding-resolves-page-org-first): if the page (center) org
- * carried no brand row, fall back to the website owning-org so pages with no
- * tenant org render the website's brand, not a blank. Extracted from the
- * hardcoded `fetchOrgBrand` arm in resolve-from-loader-config.ts.
  */
 import { fetchOrgBrand } from "@teamscala/resolver-engine/data-resolvers/fetch-org-brand";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { ResolverArgs } from "./portal-route-paths.ts";
 
-/** A null brand renders a page with no logo, colours or name — so each failure names which of the three it was. */
 export async function fetchOrgBrandWithFallback({ input, client }: ResolverArgs): Promise<unknown> {
 	const orgId = input.orgId as string | undefined;
 	const fallbackOrgId = input.fallbackOrgId as string | undefined;

package/src/resolvers/portal-route-paths.ts

@@ -1,34 +1,6 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * portal-route-paths.ts — pure path mapper for portal region routing.
- *
- * Extracted from resolve-from-loader-config.ts (the hardcoded
- * `resolvePortalRoutePaths` arm) so it can be invoked via a resolver_fn
- * registry row instead of an if-chain. Faithful extraction — no logic change.
- * The request path is the center page's builda path ("/" falls back to
- * home_path), and the per-route toolbar page follows the flat naming convention
- * `/<last-segment>-toolbar`. Pages without a matching toolbar page simply
- * resolve an empty toolbar region (the source is declared optional).
- */
-/**
- * Extract the organisation id from a portal-shaped callback/path — the single
- * authority for "which segment is the org" so the sign-in brand resolver and the
- * route resolver cannot drift on the answer (portal-branding-resolves-page-org-first).
- *
- * The canonical portal shape is `/<websiteId>/<orgId>/<path>` — the org is
- * segment 1, NOT segment 0. Reading segment 0 fed the WEBSITE id into brand
- * resolution, which resolved no org and fell back to the super-admin org — the
- * exact cross-tenant mis-branding this exists to prevent (bind-page-handler.ts,
- * found 2026-07-21).
- *
- * Single-UUID hosts keep segment 0 unchanged: scala-projects routes `/<orgId>/…`
- * and proposal/form/quiz hosts route `/<resourceId>/…` (a non-org first segment
- * that resolves to no brand and falls back as before — no regression, only the
- * correct-org improvement for the two-UUID portal shape). Returns undefined when
- * neither leading segment is a UUID.
  */
 
 export interface ResolverArgs {

package/src/resolvers/website-by-host-map.ts

@@ -1,12 +1,6 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * website-by-host-map.ts — resolves the website + body path for a host.
- *
- * Extracted from resolve-from-loader-config.ts (the hardcoded
- * `resolveWebsiteByHostMap` arm). Faithful extraction — no logic change.
  */
 import type { ResolverArgs } from "./portal-route-paths.ts";