@teamscala/service-boot 0.23.284 → 0.23.285

package/src/register-ws-routes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @system server-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 registerFnRouters, 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 type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+import type { Hono } from "hono";
+export declare function registerWsRoutes(app: Hono, config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): Promise<number>;

package/src/resolve-app-base-url.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The scala-projects app's own public hostname, read from its `service_install`
+ * row rather than hardcoded — a service knows its own deploy config only
+ * through the registry (registries-are-source-of-truth), never a literal in
+ * source. Cached for the process lifetime: this changes only on a redeploy,
+ * not per-request. Shared by every server-side path that builds a link back
+ * into the app (approval emails, mention emails, digest emails).
+ */
+export declare function resolveAppBaseUrl(): Promise<string>;

package/src/resolve-brand-favicon.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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.
+ */
+export declare function resolveBrandFaviconPath(brandOrg: string | undefined): Promise<string | null>;
+/**
+ * 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, package-poller). 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 declare function warmBrandFaviconCache(brandOrg: string | undefined): void;

package/src/resolve-from-loader-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Walks a resource_loader.sources[] graph and resolves each source in
+ * dependency order. Returns an assembled data object keyed by source key.
+ *
+ * Source types: "orpc", "prisma", "resolver_fn".
+ * Each source may declare depends_on for ordering.
+ * Params are interpolated from URL params and prior resolved data.
+ */
+interface SourceConfig {
+    key: string;
+    source: "orpc" | "prisma" | "resolver_fn";
+    model?: string;
+    where?: Record<string, unknown>;
+    select?: string[];
+    depends_on?: string[];
+    optional?: boolean;
+    resolver_fn?: string;
+    resolver_input?: Record<string, unknown>;
+    registry_filter?: Record<string, unknown>;
+    transforms?: string[];
+}
+interface LoaderConfig {
+    sources: SourceConfig[];
+    merge_strategy?: Record<string, unknown>;
+}
+export declare function resolveFromLoaderConfig(config: LoaderConfig, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function interpolateMeta(template: Record<string, unknown>, data: Record<string, unknown>): Record<string, unknown>;
+export {};

package/src/resolve-service-context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Resolves the minimum service context the bin needs to choose its launch
+ * path: connect DB, load registry, read service_install row, return kind +
+ * port. Caller is responsible for disconnecting.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+export interface ServiceContext {
+    kind: "ui" | "backend" | "runtime";
+    port: number;
+    config: ServiceInstallConfig;
+    disconnect: () => Promise<void>;
+}
+export declare function resolveServiceContext(serviceSlug: string, databaseUrl: string): Promise<ServiceContext>;

package/src/resolve-theme-mode.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @system ui-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;
+}
+export declare 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;

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

@@ -0,0 +1,2 @@
+import type { ResolverArgs } from "./portal-route-paths.ts";
+export declare function fetchOrgBrandWithFallback({ input, client }: ResolverArgs): Promise<unknown>;

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

@@ -0,0 +1,39 @@
+/**
+ * @system ui-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).
+ */
+export interface ResolverArgs {
+    input: Record<string, unknown>;
+    client: unknown;
+    params: Record<string, unknown>;
+}
+/**
+ * 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 declare function extractOrgIdFromCallbackPath(callbackUrl: string): string | undefined;
+export declare function resolvePortalRoutePaths({ input, params }: ResolverArgs): Record<string, unknown>;

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

@@ -0,0 +1,12 @@
+/**
+ * @system ui-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";
+export declare function resolveWebsiteByHostMap({ input, client, params }: ResolverArgs): Promise<Record<string, unknown> | null>;

package/src/resource-chat-inject.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Injects the generic ResourceChatLauncher block into an AUTHORISED resource
+ * page (proposal, agreement, or any gated document) — called from a gate's
+ * onAuthorized, so the floating GPT bubble lives strictly behind the email gate
+ * and every resource of that type gets it with no per-page Puck edit. It builds
+ * the resource's page content into a runtime-context string and passes it to the
+ * launcher, which forwards it to the chat as <runtime_context> — so ONE shared
+ * assistant agent answers about whichever resource is being viewed.
+ *
+ * RESOURCE-AGNOSTIC by design (one-ai-chat-system / chat-ui-is-one-canonical-block):
+ * the launcher, the chat engine, and this injector are generic; only the
+ * per-resource CONFIG differs (which agent, the copy, which resolved key holds
+ * the record). The agent id is config, not code (registries-are-source-of-truth):
+ * each resource type names a `config / <slug>-assistant-agent` row carrying
+ * { agentId }. No row (or no agent) → no injection, page renders unchanged
+ * (fail-soft).
+ */
+/** Per-resource-type injection config — the only thing that varies. */
+export interface ResourceChatOptions {
+    /** Key in `resolved` holding the record (e.g. "proposal", "agreement"). */
+    resourceKey: string;
+    /** `config` row slug carrying { agentId } (e.g. "agreement-assistant-agent"). */
+    agentConfigSlug: string;
+    /** Org id to scope the chat. If omitted, read from resolved[resourceKey].organisation_id
+     *  (proposals); agreements pass it explicitly (org isn't on the resolved record). */
+    organisationId?: string;
+    /** Overlay title-bar label (e.g. "Agreement Assistant"). */
+    title: string;
+    /** Floating button label / speech bubble (e.g. "Ask about this agreement"). */
+    launchLabel: string;
+    /** First assistant message. */
+    welcomeMessage?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** Suggested starter questions. */
+    conversationStarters?: string[];
+}
+/**
+ * Inject the generic ResourceChatLauncher behind the gate. `opts` is the only
+ * per-resource-type variation; everything else is shared.
+ */
+export declare function injectResourceChatLauncher(resolved: Record<string, unknown>, viewerEmail: string, opts: ResourceChatOptions): Promise<void>;

package/src/resource-not-found.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * One cohesive unit — the branded resource-not-found / holding page: the
+ * PrimaryResourceMissingError trigger, the org-logo resolver the page
+ * renders, and the HTML builder are tightly coupled (the builder consumes
+ * the logo; the error drives the page) and cannot be split without churn.
+ *
+ * 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.
+ */
+/**
+ * The host org's LOGO (wordmark) for the dark error page — the favicon is a
+ * tab glyph, the wrong asset at page scale (operator-observed: a lone "h"
+ * where the launcha wordmark belonged). Resolution: the service's own
+ * install row names its owner (brand_org); the org's dark-theme logo (a
+ * light-coloured mark, correct on the dark page) is preferred, light-theme
+ * second. Every step skew-tolerant: any miss → null → the builder renders a
+ * logo-less dark page.
+ *
+ * Returns the logo as an INLINE data URI (not a `/api/assets/` proxy URL) so
+ * the branded holding/error page ships the logo IN the initial HTML bytes —
+ * no second fetch, no post-paint pop-in, no dependency on the asset proxy the
+ * degraded service is failing to serve (incident 2026-07-27: the logo on a
+ * DEGRADED render-layer holding page appeared after the page painted). The
+ * logo sibling of icons-render-ssr-inline. Size-capped: a pathological
+ * (>MAX_INLINE_LOGO_BYTES) logo falls back to null rather than bloating the
+ * HTML; the page renders logo-less, never broken.
+ */
+export declare function resolveErrorPageLogo(serviceSlug: string): Promise<string | null>;
+export declare class PrimaryResourceMissingError extends Error {
+    readonly resourceType: string;
+    readonly httpStatus: number;
+    readonly empty: boolean;
+    constructor(resourceType: string, httpStatus?: number, opts?: {
+        empty?: boolean;
+    });
+}
+export declare function buildResourceNotFoundResponse(resourceType: string, logoUrl?: string | null, status?: number, opts?: {
+    homeUrl?: string;
+    empty?: boolean;
+}): Response;

package/src/run-boot-hook-list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @system server-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 "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+export declare function runBootHookList(config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): Promise<void>;

package/src/run-boot-hooks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @system server-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 "@teamscala/db/registry/loader/load-service-install-row";
+export interface BootHookContext {
+    serviceSlug: string;
+    config: ServiceInstallConfig;
+}
+export type BootHookHandler = (ctx: BootHookContext) => Promise<void> | void;
+export declare function runBootHooks(serviceSlug: string, config: ServiceInstallConfig): Promise<{
+    ran: string[];
+}>;

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

@@ -0,0 +1,10 @@
+/**
+ * @system server-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.
+ */
+export declare function startScalaToolsCurrencyWatchdog(): void;
+export declare function stopScalaToolsCurrencyWatchdog(): void;

package/src/security-headers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @system server-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 type { Context, Next } from "hono";
+export declare function injectSecurityHeaders(c: Context, next: Next): Promise<void>;

package/src/serve/serve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system runtime-serve
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Listener primitives. Provides the Bun.serve production listener (serveStart)
+ * and the WebSocket upgrade helper (upgradeWebSocket) that work identically
+ * dev and prod.
+ */
+import type { Hono } from "hono";
+/**
+ * Hono `upgradeWebSocket` helper bound to the same `createBunWebSocket()`
+ * pair that drives Bun.serve.websocket. Use exclusively from this package so
+ * the upgrade path and the message dispatch share state.
+ */
+export declare const upgradeWebSocket: import("hono/ws").UpgradeWebSocket<unknown, any, import("hono/ws").WSEvents<unknown>>;
+export interface ServeOptions {
+    /** TCP port to bind. */
+    port: number;
+    /** For logging only. */
+    serviceSlug: string;
+    /**
+     * Optional logger; defaults to console.
+     */
+    logger?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export interface ServeHandle {
+    server: ReturnType<typeof Bun.serve>;
+    stop(): void;
+}
+/**
+ * Start Bun.serve listening on the configured port. Used by:
+ *   - bootUiService when running the production bundle (`bun dist/server/index.js`)
+ *   - bootBackendService for non-UI services
+ *
+ * UI services in dev mode also call this — they run `bun src/index.ts`
+ * directly under PM2 with the same Bun.serve listener.
+ *
+ * Two-phase boot variant: when useMutableRef is true, `app` is used as the
+ * initial app for the mutable reference (minimal tool-only surface), and the
+ * caller can swap to the full app later via swapApp().
+ */
+export declare function serveStart(app: Hono, options: ServeOptions, useMutableRef?: boolean): ServeHandle;

package/src/server-error-page.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 type { ErrorReport } from "@teamscala/os/errors/error-report";
+/**
+ * Render an `ErrorReport` as a branded HTML page. Pure shaper — the caller
+ * classifies via `buildErrorReport` and resolves the logo first. Skew-tolerant
+ * by construction: a missing logo degrades to a plain branded dark page.
+ */
+export declare function buildServerErrorPageResponse(report: ErrorReport, logoUrl?: string | null): Response;

package/src/start-scheduled-jobs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Starts `service_install.scheduled_jobs[]`. Two kinds:
+ *
+ *   - `long_running`: handler invoked once at boot, runs for the lifetime of
+ *      the process (e.g. SSE subscribers, WAL watchers). Failures are logged.
+ *   - `recurring`: declared here but cron scheduling lands via pg-boss in a
+ *      follow-up — currently a no-op log.
+ *
+ * Implementations are registered by server_packages via
+ * ctx.registerScheduledJob during the mount phase.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+export declare function startScheduledJobs(config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): void;

package/src/two-phase-boot.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Two-phase boot for UI services. Splits the boot process into:
+ * 1. Minimal app (tool-only surface): ORPC, data routes, auth gates
+ * 2. Full app (with pages and hydration): adds block discovery, page routes,
+ *    client asset building, boot hooks, scheduled jobs
+ *
+ * The minimal app starts serving immediately (<10s), then the full app is
+ * built in the background and atomically swapped in. This eliminates the
+ * ~25s channel outage window during scala-agents restart.
+ */
+import { Hono } from "hono";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+import { mountServerPackages } from "./mount-server-packages.ts";
+import type { PageServerDeps } from "./ui-service.ts";
+import type { CreatePageHandler } from "./types.ts";
+/**
+ * Set the real page handler (called when Phase 2 completes).
+ */
+export declare function setPageHandler(handler: CreatePageHandler): void;
+/**
+ * Get the current page handler state.
+ */
+export declare function getPageHandlerState(): {
+    ready: boolean;
+    hasHandler: boolean;
+};
+export interface MinimalAppResult {
+    app: Hono;
+    mountRegistry: Awaited<ReturnType<typeof mountServerPackages>>;
+    apiRouteCount: number;
+    wsRouteCount: number;
+    pageRouteCount: number;
+    config: ServiceInstallConfig;
+    serviceSlug: string;
+    databaseUrl: string;
+    blockPackages: string[];
+    components: Record<string, unknown>;
+    loaded: string[];
+    skipped: string[];
+}
+export interface FullAppResult {
+    app: Hono;
+    blocks: {
+        slug: string;
+        packagePath: string;
+    }[];
+    routes: string[];
+    pgBossJobs: Array<{
+        handlerSlug: string;
+    }>;
+}
+/**
+ * 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
+ */
+export declare function buildMinimalApp(config: ServiceInstallConfig, serviceSlug: string, databaseUrl: string): Promise<MinimalAppResult>;
+/**
+ * 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.
+ */
+export declare function buildFullApp(minimalResult: MinimalAppResult, deps: PageServerDeps): Promise<FullAppResult>;
+/**
+ * Swap the minimal app for the full app. This atomically replaces the
+ * app reference that Bun.serve is using.
+ */
+export declare function swapToFullApp(fullApp: Hono, serviceSlug: string): void;

package/src/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Shared type definitions for service-boot boot helpers.
+ */
+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>;
+}
+export interface PageHandlerExtras {
+    htmlTemplate: string;
+    userId?: string;
+    orgId?: string;
+    searchParams?: Record<string, string>;
+    nonce?: string;
+}
+export type CreatePageHandler = (config: PageHandlerConfig) => (request: Request, extras: PageHandlerExtras) => Promise<Response>;
+export interface PageHandlerConfig {
+    components: Record<string, RendererComponentEntry>;
+    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;
+}
+export type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";