@teamscala/service-boot 0.23.524 → 0.23.525

package/src/resolve-service-port.ts

@@ -4,11 +4,8 @@
  */
 
 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 };
 }
 
@@ -16,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

@@ -5,7 +5,6 @@
 
 export interface ResolvedThemeMode {
 	theme: "light" | "dark";
-	/** True iff the mode came from the ?theme= embed override. */
 	embedded: boolean;
 }
 
@@ -14,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

@@ -3,7 +3,6 @@
  * @status handwritten
  */
 
-/** 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

@@ -6,7 +6,6 @@ import { fetchOrgBrand } from "@teamscala/resolver-engine/data-resolvers/fetch-o
 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

@@ -2,23 +2,6 @@
  * @system service-boot
  * @status handwritten
  */
-/**
- * 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 {
 	input: Record<string, unknown>;

package/src/resource-not-found.ts

@@ -15,16 +15,7 @@ const RESOURCE_LABELS: Record<string, string> = {
 
 export class PrimaryResourceMissingError extends Error {
 	readonly resourceType: string;
-	// HTTP status for the holding page. 404 for a genuinely missing/invalid
-	// resource (a dead /:id link); 200 for the bare root of a UUID-driven site
-	// ("no <resource> selected") — the root is a valid landing, not an error,
-	// and kind:ui services must answer GET / with 200 (verify-prod-persistent-slot).
 	readonly httpStatus: number;
-	// A page ROW exists but has zero content blocks — a content gap, not a dead
-	// link (operator ruling 2026-07-21: "if the page is empty, it should have a
-	// Puck block that says this page is empty... and then take me home"). The
-	// floor renders the "This page is empty" surface (200) instead of the dead-
-	// link "doesn't exist" surface (404). Distinct from a dead link (no row).
 	readonly empty: boolean;
 	constructor(resourceType: string, httpStatus = 404, opts?: { empty?: boolean }) {
 		super(`primary resource "${resourceType}" not found`);
@@ -39,23 +30,10 @@ export function buildResourceNotFoundResponse(
 	resourceType: string,
 	logoUrl?: string | null,
 	status = 404,
-	// Optional 4th arg keeps the existing 3-arg call sites working while letting
-	// the page binder add a "Take me home" action (operator-requested) and the
-	// empty-page variant.
 	opts?: { homeUrl?: string; empty?: boolean },
 ): Response {
 	const label = RESOURCE_LABELS[resourceType] ?? "page";
-	// Single-owner hosts show the owner's wordmark; multi-tenant hosts
-	// (no brand_org — a dead id's org is unknowable) stay platform-neutral.
-	// The helper emits the inline data-URI src with reserved width+height
-	// (logos-inline-on-branded-server-pages).
 	const logoImg = brandLogoImgTag(logoUrl, { height: 40, width: 160 });
-	// Three surfaces share this one floor (resource-not-found-is-the-root-floor):
-	//   200 root  — the BARE ROOT of a UUID-driven host ("no <resource> selected").
-	//   404 dead  — a content path with NO page row (a deleted/moved page, e.g.
-	//              /roadmap) OR a dead /:id: a link that genuinely doesn't resolve.
-	//   200 empty — a page ROW exists but has zero blocks (a content gap, not a
-	//              dead link): "This page is empty", still take-me-home.
 	const isEmpty = opts?.empty === true;
 	const isRoot = status === 200 && !isEmpty;
 	const title = isEmpty ? "Nothing here yet" : isRoot ? `No ${label} here` : "Not found";
@@ -71,8 +49,6 @@ export function buildResourceNotFoundResponse(
 			   sent to view it — there&rsquo;s nothing to see at the bare address.`
 			: `The page you&rsquo;re looking for may have been moved or removed, or the
 			   link may be incomplete.`;
-	// "Take me home" — operator-requested action on every not-found/empty surface.
-	// Omitted on the bare-root landing (it IS home). Defaults to the host root.
 	const homeUrl = opts?.homeUrl ?? "/";
 	const homeLink = isRoot
 		? ""

package/src/select-service-routes.ts

@@ -5,17 +5,10 @@
 
 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;
@@ -28,13 +21,6 @@ function comparePatternSpecificity(a: string, b: string): number {
 	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,

package/src/theme-fonts-link.ts

@@ -9,15 +9,11 @@ interface ThemeFontsConfig {
 	fonts?: Record<string, string>;
 }
 
-/** The primary family name of a CSS font stack: "Inter, sans-serif" →
- * "Inter"; "Playfair Display" → "Playfair Display". */
 export function primaryFontFamily(stack: string): string {
 	const first = stack.split(",")[0] ?? "";
 	return first.trim().replace(/^['"]|['"]$/g, "");
 }
 
-/** The declared theme families, deduplicated by primary family, in row
- * order (body, heading, manuscript, mono…). Empty when the row is absent. */
 export function themeFontFamilies(): string[] {
 	try {
 		const config = getEntryConfig<ThemeFontsConfig>("css_theme", "default");
@@ -37,7 +33,6 @@ export function themeFontFamilies(): string[] {
 	}
 }
 
-/** The <link> tag loading every declared theme family, or "" when none. */
 export function themeFontsLink(): string {
 	const families = themeFontFamilies();
 	if (families.length === 0) return "";

package/src/two-phase-full-app.ts

@@ -3,52 +3,8 @@
  * @status handwritten
  */
 
-/**
- * Build the full app with hydration. This adds the expensive operations that
- * were deferred from the minimal app:
- * - Client asset building (Vite build)
- * - Boot hooks (may have expensive initialization)
- * - Scheduled jobs (can start later)
- * - pg-boss (can start later)
- *
- * This runs in the background after the minimal app is already serving.
- * NOTE: All routes (including page routes) are already registered in Phase 1,
- * so we don't need to modify the app here. The app reference stays the same.
- */
 
-	// Client asset building (expensive: Vite build).
-	//
-	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
-	// This was awaited unguarded, so a throw here aborted buildFullApp before
-	// mountPgBoss ran, and the caller's catch logged
-	// "Failed to build full app, continuing with minimal app" — which reads as a
-	// UI-only degradation while having silently killed every pg-boss handler on
-	// the service.
-	//
-	// Measured 2026-07-30: a stale @teamscala/portal-ui artifact still importing
-	// the retired @teamgbg scope threw ENOENT on a missing theme CSS file in
-	// scala-agents. Zero "scheduledJobs DONE" lines appeared for ~20 minutes
-	// across repeated boots, the pane-outbox drain never mounted, and the
-	// operator's WhatsApp assistant went silent — because of a stylesheet. The
-	// service stayed `online` and healthy throughout, so nothing surfaced it.
-	//
-	// The steps after this one do not depend on client assets: pg-boss needs the
-	// registry and the DB, not a bundle. Ordering it behind a Vite build was
-	// incidental, so the coupling was never intended.
 
-	// pg-boss (mount for UI services - wasn't mounted in minimal app)
-	//
-	// Wrapped for the SAME reason buildClientAssets above is, in the other
-	// direction: a background-work failure must not cost the page. Unwrapped,
-	// anything mountPgBoss throws propagates out of the full-app build, the
-	// caller falls back to the MINIMAL app, and the service serves 0 api routes
-	// with /health 503 — so the tunnel health check fails and the site is
-	// unreachable from outside while localhost answers in 0.1s.
-	//
-	// Measured 2026-08-31 on scala-projects: a deps refresh moved pg-boss to a
-	// build expecting a newer shared pgboss schema than the database carried, its
-	// migration threw, and an outage of every page followed from a scheduled-job
-	// dependency. Jobs are the degradable half; pages are not.
 
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
@@ -78,9 +34,6 @@ export async function buildFullApp(
 		await buildClientAssets(serviceSlug);
 		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
 	} catch (error) {
-		// Loud but non-fatal: the tombstone manifest written by buildClientAssets
-		// already makes SSR serve the prior bundle, so degrading here costs the
-		// new bundle, never the background work.
 		log.error(
 			`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets FAILED — continuing to scheduled jobs and pg-boss (a client-asset failure must not stop background work)`,
 			{ error: error instanceof Error ? error.message : String(error) },
@@ -107,23 +60,6 @@ export async function buildFullApp(
 		);
 	}
 
-	// The readiness flip is gated on a VERIFIED client build, never on "phase 2
-	// got this far". buildClientAssets's failure above is deliberately non-fatal
-	// for background work — but a deployment whose client build never ran (or
-	// whose tombstone names unbuilt files) must not flip ready and serve pages:
-	// every served asset URL would 404 while /health and the deploy report ok.
-	// Measured 2026-09-01: proposals.scala.business served a client-facing
-	// proposal unstyled while Railway reported SUCCESS, because the phase-1
-	// catch let boot continue past the build and the flip never checked the
-	// build's outcome (`a-component-may-not-report-a-state-it-has-not-verified`).
-	// The throw lands in ui-service's boot.client-build-failed catch, which
-	// keeps the minimal app: pages and /health stay 503 (cleanly unavailable)
-	// while the pg-boss jobs mounted above KEEP RUNNING. On Railway the
-	// healthcheck (healthcheckPath: /health) then fails and the previous good
-	// deployment keeps traffic — the deploy reports FAILED, never SUCCESS.
-	// readiness-gated-boot: a service is "fully-ready or cleanly-unavailable";
-	// a UI service that cannot serve its bundle is not ready
-	// (`liveness-by-capability-not-process-existence`).
 	const clientBuild = await verifyClientBuildAssets();
 	if (!clientBuild.ok) {
 		throw new Error(
@@ -139,20 +75,12 @@ export async function buildFullApp(
 			`${Object.keys(components).length} component(s)`,
 	);
 
-	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it.
-	// Client-only services (render_mode=client) have no SSR page handler — skip
-	// (they serve via the client bundle, never SSR). Guarded so undefined is a
-	// no-op rather than a crash.
 	if (deps.createPageHandler) {
 		setPageHandler(deps.createPageHandler);
 		log.info(
 			`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
 		);
 	} else {
-		// The full app IS built — this service simply never renders server-side,
-		// so readiness is flipped directly rather than as a side effect of
-		// registering an SSR handler that will never exist. Without this a
-		// client-only service is permanently un-ready (see markFullAppReady).
 		markFullAppReady();
 		log.info(
 			`[two-phase-boot:${serviceSlug}] Client-only mode (render_mode=client) — no SSR page handler registered`,
@@ -172,10 +100,6 @@ export async function buildFullApp(
 	};
 }
 
-/**
- * Swap the minimal app for the full app. This atomically replaces the
- * app reference that Bun.serve is using.
- */
 export function swapToFullApp(fullApp: Hono, serviceSlug: string): void {
 	const oldLabel = swapApp(fullApp, "full");
 	const log = getAppLogger();

package/src/two-phase-minimal-app.ts

@@ -3,39 +3,6 @@
  * @status handwritten
  */
 
-/**
- * Build the minimal tool-only app. This excludes the expensive operations:
- * - Client asset building (Vite build)
- * - Boot hooks (may have expensive initialization)
- * - Scheduled jobs (can start later)
- * - pg-boss (can start later)
- *
- * CRITICAL: All route registration MUST happen here before serving, because
- * Hono's RegExpRouter compiles on the first request and becomes immutable.
- * Once compiled, no new routes can be added. So we include:
- * - Block discovery and page routes (registers all page paths)
- * - All other routes (API, WS, data, static assets)
- *
- * The minimal app includes everything needed for MCP tools and ORPC:
- * - Error handling, readiness gate, health check
- * - Security headers, CORS, compression, timing
- * - Content gate access, auth gates, static assets
- * - ORPC router, API routes, WS routes, data routes, page routes
- */
-
-	// Fire independent I/O + compilation NOW, overlapping with the gate chain
-	// below. These three touch NO app route and have no ordering dependency on
-	// the gate/mount sequence, so they run concurrently with it:
-	// - preloadServerPackages: warms Bun's module cache (CPU-bound compilation
-	//   that overlaps the gate chain's cross-internet DB I/O — same speculative
-	//   pattern as create-boot-pipeline's preloads). mountServerPackages later
-	//   hits the cache (instant imports), paying only the ~33ms of mount work.
-	// - initGateTtls: loads config rows into module-level vars. The TTL getters
-	//   are read at REQUEST time (inside route-handler closures), not at boot,
-	//   so this only needs to finish before serving — safe to run in parallel.
-	// - discoverBlocks: loads the page-manifest (no app mutation, no gate
-	//   dependency). Its result is consumed by registerPageRoutes much later.
-
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { createTimer } from "@teamscala/timing/create-timer";
@@ -55,7 +22,7 @@ import { attachPortalMembers } from "./attach-portal-members.ts";
 import { attachTransfersUpload } from "./attach-transfers-upload.ts";
 import { attachAuthGate } from "./auth-gate.ts";
 import { csrfProtection } from "./csrf-protection.ts";
-import { attachRequestLogger } from "./install-logging.ts";
+import { attachRequestLogger } from "@teamscala/logger/install-logging";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import { mountOrpcRouter } from "./mount-orpc-router.ts";
 import { mountServerPackages, preloadServerPackages } from "./mount-server-packages.ts";
@@ -101,13 +68,6 @@ export async function buildMinimalApp(
 
 	const app = new Hono();
 
-	// Per-step instrumentation inside the boot-ui-service phase. Same
-	// createTimer + wall-clock convention as create-boot-pipeline's runPhase
-	// (timing-is-the-only-timing, per-phase-instrumentation) — NOT a second
-	// telemetry surface. The boot-ui-service phase is 60% of boot; this
-	// breakdown localises the cost so optimisation targets the real hotspot
-	// instead of guessing. Spans flow to GlitchTip (timing's trace-emitter is
-	// wired by the time we reach here); the breakdown line is `pm2 logs`-visible.
 	const stepTimings: Record<string, number> = {};
 	async function runStep<T>(step: string, fn: () => Promise<T>): Promise<T> {
 		const timer = createTimer(`${serviceSlug}:boot.minimal.${step}`);
@@ -119,7 +79,6 @@ export async function buildMinimalApp(
 		}
 	}
 
-	// Error handlers
 	app.onError(createRequestErrorHandler("service-boot:minimal"));
 
 	app.notFound(async (c) => {
@@ -131,7 +90,6 @@ export async function buildMinimalApp(
 		return c.json({ error: "Not Found" }, 404);
 	});
 
-	// Core middleware
 	app.use("*", readinessGate);
 	app.get("/health", healthHandler);
 	app.use("*", injectSecurityHeaders);
@@ -151,19 +109,7 @@ export async function buildMinimalApp(
 	);
 	app.use("*", compress());
 	app.use("*", timing());
-	// CSRF (`security-csrf-protection`): state-changing form-element requests
-	// must carry a trusted Origin — derived set (managed base domain +
-	// builda_websites custom domains via isTrustedAuthOrigin), never an
-	// allowlist beside better-auth's. Registered after security headers, before
-	// every route + gate.
 	app.use("*", csrfProtection());
-	// GLOBAL body limit (`security-body-limit`): every request body is bounded
-	// BEFORE any handler buffers it — a per-route file.size check AFTER
-	// formData() has buffered is a report, not a limit. 30MB sits above the
-	// 25MB transfers-upload maximum; routes wanting a smaller bound mount their
-	// own bodyLimit BEFORE this one (Hono runs matching middleware in
-	// registration order, and /api/rpc registers its 10MB limit in
-	// mount-orpc-router).
 	app.use(
 		"*",
 		bodyLimit({
@@ -180,20 +126,8 @@ export async function buildMinimalApp(
 	);
 	const ttlPromise = runStep("init-gate-ttls", () => initGateTtls());
 
-	// Public access endpoints — MUST be registered before the auth gate (Hono
-	// dispatches middleware + handlers in registration order; the content-gate
-	// POST routes and magic-link endpoints are public and must be reachable
-	// without a session, so they precede the auth gate's app.use("*") wildcard).
-	// These are mutually independent — distinct paths, no shared mutable state
-	// beyond the Hono app's synchronous route array — so they parallelise.
 	await runStep("public-routes", () =>
 		Promise.all([
-			// EVERY REGISTERED GATE'S ACCESS ENDPOINT (content-gate/catalog.ts).
-			// The same catalog the SSR gate sequence iterates, so the endpoint that
-			// MINTS a gate's token and the gate that VERIFIES it cannot disagree
-			// about which gates exist — this list and that one were two copies of
-			// one fact, and a gate added to one and missed in the other is a page
-			// that gates content with no way to unlock it.
 			...CONTENT_GATES.map((entry) =>
 				attachContentGateAccess(app, serviceSlug, entry.access),
 			),
@@ -205,27 +139,14 @@ export async function buildMinimalApp(
 		]),
 	);
 
-	// Auth gate — registers /api/auth/* + the session-check wildcard middleware.
-	// MUST follow the public routes above (load-bearing Hono registration order)
-	// and MUST precede mountServerPackages: server-package daemon routes (e.g.
-	// cli-session's /rpc/*) are subject to the session gate, which requires the
-	// gate's wildcard registered first to apply. Running these concurrently would
-	// make that ordering non-deterministic — so the gate stays serial here.
 	await runStep("attach-auth-gate", () =>
 		attachAuthGate(app, config, serviceSlug),
 	);
 	registerStaticAssets(app, serviceSlug, config.brand_org);
 
-	// Server packages — the cold imports were preloaded above and are now in
-	// Bun's module cache, so this pays only the mount work (~33ms, not ~2.8s of
-	// serial compilation). Route registration happens HERE (after the auth gate),
-	// preserving the gate-vs-daemon-route ordering.
 	const mountRegistry = await runStep("mount-server-packages", () =>
 		mountServerPackages(app, config, serviceSlug, getSharedDb),
 	);
-	// Ensure the speculative preload finished before proceeding (it populates
-	// the same cache mountServerPackages just consumed; awaiting now is a no-op
-	// if the preload already settled, and makes the ordering guarantee explicit).
 	await preloadPromise;
 	const apiRouteCount = registerApiRoutes(app, config, mountRegistry, serviceSlug);
 
@@ -233,17 +154,10 @@ export async function buildMinimalApp(
 		await runStep("mount-orpc-router", () => mountOrpcRouter(app, serviceSlug));
 	}
 
-	// Register the in-process ORPC server client BEFORE discoverBlocks — it
-	// calls getServerClient() which needs the client set here. Must follow
-	// mount-orpc-router (which builds the router getAppRouter uses).
-	// Previously ran inside register-page-routes (too late — discoverBlocks
-	// fired before it, hitting the empty-router fallback).
 	await runStep("register-page-server-client", () =>
 		registerPageServerClient(serviceSlug),
 	);
 
-	// NOW load the generated manifest (getServerClient is set). Awaited below
-	// before register-page-routes consumes the result.
 	const discoverPromise = runStep("load-page-manifest", () =>
 		loadPageManifest(serviceSlug),
 	);
@@ -252,14 +166,8 @@ export async function buildMinimalApp(
 		registerWsRoutes(app, config, mountRegistry, serviceSlug, upgradeWebSocket),
 	);
 
-	// Resolve the deferred TTL load (started at the top — should be long done,
-	// overlapped with the gate chain + mount work). The getters are read at
-	// request time, but the cache must be populated before the first request.
 	await ttlPromise;
 
-	// CRITICAL: Block discovery and page routes MUST be registered BEFORE serving,
-	// because Hono's RegExpRouter compiles on first request and becomes immutable.
-	// We defer only client asset building (expensive Vite build) to Phase 2.
 	let components: Awaited<ReturnType<typeof loadPageManifest>>;
 	try {
 		components = await discoverPromise;
@@ -276,15 +184,10 @@ export async function buildMinimalApp(
 	);
 
 
-	// Run boot hooks BEFORE serving - some hooks may register routes and must
-	// run before Hono's matcher is compiled by the first request
 	await runStep("run-boot-hooks", () =>
 		runBootHookList(config, mountRegistry, serviceSlug),
 	);
 
-	// Register page routes with a dynamic handler that delegates to the real handler once Phase 2 completes.
-	// All route paths must be registered before serving to avoid Hono
-	// RegExpRouter compilation issues (matcher becomes immutable).
 	const registeredPageRoutes = await runStep("register-page-routes", () =>
 		registerPageRoutes({
 			app,
@@ -299,10 +202,6 @@ export async function buildMinimalApp(
 	const steps = Object.entries(stepTimings)
 		.map(([step, ms]) => `${step}=${ms}ms`)
 		.join(" ");
-	// NOTE: several steps run concurrently (speculative preload, init-gate-ttls,
-	// discover-blocks overlap the gate chain), so the step sum exceeds the
-	// wall-clock buildMinimalApp duration. Compare to the boot-ui-service phase
-	// timing in the Boot complete line for the true wall-clock cost.
 	log.info(
 		`[two-phase-boot:${serviceSlug}] buildMinimalApp breakdown (steps overlap) — ${steps}`,
 	);
@@ -322,9 +221,6 @@ export async function buildMinimalApp(
 		databaseUrl,
 		blockPackages,
 		components,
-		// The generated manifest IS the loaded set — every entry it exports is a
-		// block this service renders, so there is no "skipped" half any more. A
-		// row that cannot produce a component fails codegen, not boot.
 		loaded: Object.keys(components),
 		skipped: [] as string[],
 	};

package/src/types.ts

@@ -8,9 +8,6 @@ type RendererComponent = (props: Record<string, unknown>) => unknown;
 export interface RendererComponentEntry {
 	render: RendererComponent;
 	fields?: Record<string, { type: string }>;
-	/** block_schema.defaults, carried onto the entry by discoverBlocks so
-	 *  buildPuckConfig merges them under authored props at SSR
-	 *  (blocks-fully-programmable). */
 	defaultProps?: Record<string, unknown>;
 }
 
@@ -31,18 +28,7 @@ export interface PageHandlerConfig {
 	providers?: string[];
 	loadData: (request: Request) => Promise<unknown>;
 	renderMode?: "public" | "portals" | "utility";
-	/**
-	 * Owning service slug — used by the page-server render catch to resolve
-	 * the branded logo on the render-error page. Mirrors service-runtime's
-	 * PageHandlerConfig.
-	 */
 	serviceSlug?: string;
-	/**
-	 * Redirect a signed-in user's `/` to their org-scoped portal dashboard.
-	 * Set only for services serving a `/*` catchall page_route (the portal);
-	 * single-site portal-mode services serve their real page at `/`.
-	 * Mirrors service-runtime's PageHandlerConfig (1.15.82).
-	 */
 	portalHomeRedirect?: boolean;
 }
 

package/src/ui-service.ts

@@ -17,32 +17,7 @@
  * place and is NOT undone.
  */
 
-	// Resolve the listen port through the SHARED resolver (`resolveServicePort`),
-	// the same one the backend branch uses. The registry wins wherever it has an
-	// opinion and a contradicting PORT env is reported, never silently obeyed —
-	// full reasoning in that file.
-	//
-	// This branch previously took `process.env.PORT` unconditionally, which is
-	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
-	// leaked env and silently split that daemon's traffic (2026-07-31). On the
-	// dev host the registry wins a conflict (below). On Railway the injected PORT
-	// wins instead — Railway healthchecks exactly that port, and the row's port
-	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
-	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
-	// path in the resolver).
-
-			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
-			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
-			// The minimal-app fallback keeps serving SSR from the LAST-successful
-			// manifest (now a tombstone, see build-client-assets.ts), so the page
-			// looks "up" while the client bundle is stale. Without this signal the
-			// failure is buried in boot stderr and a published fix that reached
-			// node_modules but failed to bundle ships invisibly stale (the
-			// scala-agents 2026-07-18 incident: ui-foundation@3.4.5 installed but
-			// served pre-fix bytes across restarts while node_modules was
-			// mid-install). The boot.client-build-failed event routes into
-			// event-log's 7-day retention → surfaces in GlitchTip as an incident
-			// trail the operator actually watches.
+
 
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
@@ -91,7 +66,6 @@ export async function bootUiService(
 	const log = getAppLogger();
 	const startTime = Date.now();
 
-	// Phase 1: Build minimal tool-only app
 	const minimalAppResult = await buildMinimalApp(
 		config,
 		serviceSlug,
@@ -102,12 +76,6 @@ export async function bootUiService(
 
 	const isRailway = Boolean(process.env.RAILWAY_ENVIRONMENT);
 	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
-	// The APP binds its PRIVATE port (app_port) when present — for scale-to-zero
-	// services `port` is the ACTIVATOR's ingress (what callers resolve), not the
-	// app's bind. Falling back to `port` keeps RESIDENT + unmigrated services
-	// unchanged. Without this, a migrated row (port=activator) would make the app
-	// bind the activator's port → SO_REUSEPORT silent load-balancing (the
-	// service-ports-from-registry trap: clean boot, two owners in ss -ltnp).
 	const declaredAppPort = config.app_port ?? config.port;
 	const resolution = resolveServicePort(envPort, declaredAppPort, isRailway);
 	if ("error" in resolution) {
@@ -129,21 +97,17 @@ export async function bootUiService(
 	}
 	const port = requireValidPort(resolution.port, serviceSlug);
 
-	// service-runtime owns the TCP listener. service-boot only composes the app
-	// and starts the two-phase build; the runtime binds the returned app.
 	const minimalReadyTime = Date.now();
 	const minimalDuration = minimalReadyTime - startTime;
 	log.info(
 		`[ui-service-boot:${serviceSlug}] Minimal app composed on port ${port} in ${minimalDuration}ms`,
 	);
 
-	// FLIP READY SWITCH: minimal app is ready, MCP tools can connect
 	setReady();
 	log.info(
 		`[ui-service-boot:${serviceSlug}] Ready gate flipped - MCP tools can now connect (full app building in background)`,
 	);
 
-	// Phase 2: Build full app in background (non-blocking)
 	;(async () => {
 		try {
 			const PHASE2_TIMEOUT_MS = 120_000;
@@ -159,7 +123,6 @@ export async function bootUiService(
 			const fullBuildTime = Date.now();
 			const fullDuration = fullBuildTime - startTime;
 
-			// Swap the app reference atomically
 			swapToFullApp(fullAppResult.app, serviceSlug);
 
 			log.info(
@@ -178,13 +141,9 @@ export async function bootUiService(
 					at: new Date().toISOString(),
 				},
 			});
-			// Continue with minimal app - better than crashing
 		}
 	})();
 
-	// Return result compatible with the existing UiServiceBootResult interface
-	// Note: blocks/routes will be empty initially since they're built in the background.
-	// The service is operational for MCP tools.
 	return {
 		kind: "ui",
 		blocks: [], // Will be populated when full app builds