@teamscala/service-boot 0.23.523 → 0.23.525

package/src/resource-not-found.ts

@@ -1,30 +1,6 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * One cohesive unit — the branded resource-not-found / holding page FLOOR:
- * the PrimaryResourceMissingError trigger and the HTML builder (the builder
- * consumes a logoUrl argument; the org-logo resolvers live in
- * error-page-logo.ts).
- *
- * Branded 404 for registry page routes whose PRIMARY resource is missing.
- *
- * A route that declares `resource_type` (proposal, form, quiz, agreement…)
- * is meaningless without that entity. Before this existed, a dead link
- * (wrong id, deleted row) fell through the loader with nulls and rendered
- * whatever default content the shell could scrape together — leaking
- * internal pages (the "Vision Toolbar" incident, operator-observed
- * 2026-06-05) on the org's own branded host, with a 200 status that
- * search engines and link unfurlers would happily cache.
- *
- * The replacement: loadData throws PrimaryResourceMissingError; the page
- * binder maps it to a minimal branded 404 — correct status, noindex, the
- * host's own favicon (which resolves the owning org per brand_org), and a
- * plain human sentence. Deliberately NOT a puck page: the error surface
- * must render even when data loading is the thing that failed. A
- * website-editable /404 puck page can layer on top later; this is the
- * floor that must always exist.
  */
 
 import { brandLogoImgTag } from "@teamscala/os/brand/brand-logo-img-tag";
@@ -39,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`);
@@ -63,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";
@@ -95,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/run-boot-hook-list.ts

@@ -1,18 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Runs the service's boot hooks. A server_package registers a hook via
- * ctx.registerBootHook during the mount phase; a hook registered by an
- * INSTALLED server_package is intended to run (the package is installed
- * because the service wants it). This therefore invokes EVERY registered
- * hook — those declared in `service_install.boot_hooks[]` first (preserving
- * their declared order), then any registered-but-undeclared hooks. Requiring a
- * hook to be BOTH registered by its package AND re-declared in boot_hooks is a
- * double-declaration footgun — it left the realtime-utils pg-notify bridge
- * registered-but-never-invoked (boot_hooks was null), so the live-refresh
- * relay never started (2026-06-29).
  */
 
 import type { ServiceInstallConfig } from "./load-service-install-row";

package/src/run-boot-hooks.ts

@@ -1,24 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Runs service_install.boot_hooks in declaration order. A boot hook is a
- * registry-declared, one-shot startup function that needs to execute after
- * prisma + registry are ready but before the HTTP server starts serving.
- * Used for custom startup logic (stale-run reconciliation, cache hydration,
- * ALS seeding, long-running watcher start) that doesn't fit the pg-boss
- * recurring model and is too specific to be a generic installer step.
- *
- * Each hook is resolved by dynamic-importing its handler_slug (or slug when
- * handler_slug is absent) and awaiting its default export. The export must
- * be an async function accepting a BootHookContext. Hooks are invoked in
- * ascending order of their `order` field (default 100).
- *
- * Failures are fatal. The installer has no partial-boot concept: if a
- * declared hook cannot run, the service is broken, and booting anyway would
- * mask the regression. BootFatalError is thrown to propagate to the
- * top-level boot-error handler.
  */
 
 import type { ServiceInstallConfig } from "./load-service-install-row";

package/src/scala-tools-currency-watchdog.ts

@@ -1,12 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Polls the installed scala-tools package against GitHub Packages and repairs
- * stale daemon tooling by reinstalling and letting PM2 restart the process.
- * The fetch routes through `getGithubPackagesLatestVersion` so the URL
- * encoding and GitHub-Packages auth header live in the typed primitive.
  */
 
 import { recordEvent } from "@teamscala/event-log/record-event";

package/src/security-headers.ts

@@ -1,12 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Middleware that injects security headers into every response.
- * Uses Hono's secureHeaders as the base for standard headers (X-Content-Type-Options,
- * X-Frame-Options, Referrer-Policy, etc.), then layers registry-driven CSP with
- * nonce injection on top.
  */
 
 import { getConfigObject } from "@teamscala/db/registry/config";

package/src/select-service-routes.ts

@@ -1,37 +1,14 @@
 /**
- * @system ui-service-boot
+ * @system 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;
@@ -44,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/server-error-page.ts

@@ -1,24 +1,6 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The branded HTML error page for a FAILED PAGE RENDER — the page-server
- * render catch's response surface (constitution `error-responses-via-error-
- * report`). When SSR resolve+render fails (render budget exhausted, DEGRADED
- * protective layer, a thrown loader), the browser is mid-navigation: serving
- * a JSON body there is the violation this closes (2026-07-24: the operator
- * saw a raw `{"error":"Request failed"}` blob where the dashboard should be).
- *
- * Classification stays in `buildErrorReport` (`@teamscala/os`) — the ONE
- * classifier; this file is ONLY the HTML shaper for the page-navigation
- * surface (API/ORPC `onError` keeps the JSON body, consumed by code). It
- * renders the report's already-decided status + Retry-After + message, so the
- * screen, the log line, and the GlitchTip event all share one `errorId`.
- *
- * Deliberately NOT a Puck page: it must render even when data loading is what
- * failed. Sibling of `resource-not-found.ts` (the missing-resource floor) —
- * same dark branded template + org-logo resolver, distinct trigger.
  */
 
 import { escapeHtml } from "@teamscala/formatters/escapeHtml";

package/src/theme-fonts-link.ts

@@ -1,21 +1,6 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Derives the document head's Google Fonts link from the `css_theme` row's
- * `fonts` map — the ONE source for the families a page's variants reference
- * (`the-theme-decides-colour-not-the-component` extends to type). The old
- * envelope hard-coded Inter, so a proposal heading naming a manuscript serif
- * ("Playfair Display") never had its family loaded and fell back to Times
- * (2026-09-02). Now every family the row declares is loaded; a family a
- * variant names that the row does not declare is a row defect, caught at the
- * row's schema boundary.
- *
- * Read from the boot registry cache (captured at service boot, the same
- * semantics as the resource_loader capture) and guarded: a missing or
- * unreadable row degrades to NO fonts link — system fonts render, the page
- * still works. This module must never throw into the document builder.
  */
 
 import { getEntryConfig } from "@teamscala/db/registry/accessors";
@@ -24,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");
@@ -52,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/transfers/presigned-upload.ts

@@ -1,32 +1,6 @@
 /**
  * @system service-boot
- * @status handwritten — none derivable: searched the api_route row (fn-transfers-presigned-upload) which declares path/handler_config/input but not a body, the codegen outputs (host-bus-handler-contracts emits wiring + suites FROM rows, never procedure bodies), reference/package-catalog.md (object-storage signs a key; it carries no upload-policy primitive: no size/type/dir-scheme package to install), and the retired mount attach-transfers-upload.ts (the policy's origin, not a derivation target) — nothing generates a policy-checking procedure body.
- * @edit edit directly
- *
- * The fn.transfers.presignedUpload procedure body (api_route
- * `fn-transfers-presigned-upload`, authed: input + context). It replaces the
- * FormData POST /api/transfers/upload mount for every UI caller: the browser
- * asks for a SIGNED PUT URL for one key, uploads the bytes straight to the
- * store, and persists the SERVABLE key — so the file never crosses the
- * service and the call is one JSON request instead of a multipart body.
- *
- * The policy the mount carried lives here, and is the SAME policy: the
- * MAX_FILE_SIZE / ALLOWED_TYPES refusals (with their 413/415 statuses intact
- * through the ORPC codes below), the USER-scoped key scheme
- * (`users/<userId>/<dir>/<dir-singular>-<ts>.<ext>`), the unknown-dir
- * fallback to `uploads`, and the servable value returned as `url` with
- * `thumbUrl` mirroring it (the stored value is the servable value —
- * single-logo-pathway, so display code reads the column with no rewriting).
- * The key is derived from `context.user.id`, never from input: a caller
- * cannot mint a URL under another user's prefix.
- *
- * HONEST RESIDUAL: the size refusal reads the DECLARED fileSize, because the
- * bytes no longer pass through here — the store enforces the signature's type
- * and expiry, not a byte count. The mount's Content-Length check was equally
- * a declared-value check (an attacker sent the bytes either way); what
- * changes is that a lying client is now bounded by the URL's TTL instead of a
- * boot-level body limit. A real byte bound belongs to the bucket, not to this
- * handler.
+ * @status handwritten
  */
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { getPresignedUrl } from "@teamscala/object-storage/create/presigned-url";

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

@@ -1,60 +1,10 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Phase 2 of the two-phase boot: the full app. Adds the expensive operations
- * deferred from phase 1 (two-phase-minimal-app.ts) — client asset building
- * (Vite build), pg-boss, the readiness/page-handler flip — and is swapped
- * in atomically once complete.
  */
 
-/**
- * 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";
@@ -84,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) },
@@ -113,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(
@@ -145,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`,
@@ -178,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

@@ -1,47 +1,8 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Phase 1 of the two-phase boot: the minimal tool-only app (ORPC, data
- * routes, auth gates) that serves immediately (<10s); phase 2
- * (two-phase-full-app.ts) builds the full app in the background and swaps
- * it in atomically — eliminating the ~25s boot outage window.
  */
 
-/**
- * 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";
@@ -61,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";
@@ -107,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}`);
@@ -125,7 +79,6 @@ export async function buildMinimalApp(
 		}
 	}
 
-	// Error handlers
 	app.onError(createRequestErrorHandler("service-boot:minimal"));
 
 	app.notFound(async (c) => {
@@ -137,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);
@@ -157,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({
@@ -186,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),
 			),
@@ -211,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);
 
@@ -239,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),
 	);
@@ -258,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;
@@ -282,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,
@@ -305,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}`,
 	);
@@ -328,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[],
 	};