@teamscala/service-boot 0.23.345 → 0.23.347

package/src/serve/stamp-transport-identity.d.ts

@@ -1,39 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Stamp transport-derived identity onto a request — the single shared stamp
- * point used by BOTH serve paths (direct `createFetchHandler` + mutable-ref
- * `fetchWithMutableApp`), so every request on every UI service carries the
- * same identity regardless of boot mode.
- *
- * Two identity layers, both transport-derived (no-client-controlled-trust-
- * signals — never from a client-controllable header):
- *   1. `x-caller-remote-address` / `-port` — the unforgeable socket peer, from
- *      `Bun.serve.requestIP`. ALWAYS sanitised (any client-supplied spoof
- *      deleted) then set to the verified peer. The /mcp + fleet loopback gates
- *      read this.
- *   2. `x-caller-local-comm` / `-cmd` — for a LOOPBACK peer with no forwarding
- *      header (a local `fetch` carries no CF-Connecting-IP), the owning local
- *      PROCESS resolved via /proc (@teamscala/proc-walker). Names the daemon
- *      behind every local request on the access log — including an unidentified
- *      sweeper. Attribution only (trust stays transport-derived).
- *
- * Best-effort + never throws: a resolution miss returns the original request
- * unchanged (the request is always served; identity degrades to address-only).
- * WebSocket upgrades are returned untouched (Bun tracks upgrades by Request
- * identity — a clone can never upgrade).
- */
-/**
- * Preserve useful process attribution without copying arbitrary argv into logs.
- * Arguments routinely contain bearer headers, inline scripts, URLs and secret
- * values. There is no complete flag-name redaction list, so the safe boundary
- * is structural: retain argv[0] and state that arguments were removed.
- */
-export declare function summariseLocalCommand(cmdline: readonly string[]): string | null;
-/**
- * Return a Request with transport-identity headers stamped, or the original
- * `req` when no stamping is needed/possible. Never throws.
- */
-export declare function stampTransportIdentity(req: Request, server: ReturnType<typeof Bun.serve>): Request;

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

@@ -1,29 +0,0 @@
-/**
- * @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

@@ -1,18 +0,0 @@
-/**
- * @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

@@ -1,176 +0,0 @@
-/**
- * @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, type Context } 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 on an SSR service).
- *
- * Registering the SSR handler implies the full app is built, so this also flips
- * readiness — but the reverse does NOT hold, which is why `markFullAppReady`
- * exists separately. See its note.
- */
-export declare function setPageHandler(handler: CreatePageHandler): void;
-/**
- * Flip readiness once phase 2 has built the full app.
- *
- * SEPARATE FROM `setPageHandler` BECAUSE THE TWO FACTS CAME APART. Readiness
- * means "phase 2 finished"; the page handler means "this service renders pages
- * server-side". Every service was SSR, so one flag honestly carried both — until
- * `render_mode=client` (`granular runtime`) made a service that completes phase 2
- * and never registers an SSR handler.
- *
- * Leaving readiness inside `setPageHandler` made such a service PERMANENTLY
- * un-ready: `/health` answered `{"status":"starting"}` forever while the process
- * was healthy and serving. That is the failure `readiness-gated-boot` is written
- * against — a service must be "binary: fully-ready or cleanly-unavailable", and
- * a never-ready health signal makes the activator's wake gate and every
- * health-gated router treat a working service as down.
- *
- * Measured 2026-08-07 on scala-agents-ui: boot completed in 5023ms, "Full app
- * built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and `/health`
- * still reported starting — while three untouched UI services reported ok.
- */
-export declare function markFullAppReady(): void;
-/**
- * Reset both phase-2 flags. TEST-ONLY.
- *
- * `fullAppReady` is module state that only ever transitions false -> true in
- * production, and Bun shares a module instance across every test file in a run —
- * so the SSR readiness test and the client-only readiness test contaminate each
- * other purely by file order. Splitting them across files does NOT isolate them;
- * it only hides the coupling until CI runs them together.
- *
- * A test that passes alone and fails in a suite is worse than no test, so the
- * reset is exported rather than left as an ordering convention nobody can see.
- * Never called from production code — `setPageHandler`/`markFullAppReady` are
- * the only writers on the boot path.
- */
-export declare function __resetPhase2StateForTest(): void;
-/**
- * Get the current page handler state.
- */
-export declare function getPageHandlerState(): {
-    ready: boolean;
-    hasHandler: boolean;
-};
-/**
- * `/health` for a UI service — 200 ONLY once the full app can actually render
- * a page, 503 before that.
- *
- * This endpoint is not decoration: it is the wake gate for every scale-to-zero
- * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
- * connection through a cold wake and pipes it the instant `isHealthy(port)` —
- * a plain `GET /health` — returns ok, which is what `scale-to-zero-apps-sleep-
- * on-demand` means by "`/health`-gates the wake (the client never sees a boot
- * 503)".
- *
- * It previously answered a flat `{status:"ok"}` as soon as the MINIMAL app was
- * serving, because the readiness gate flips ready after phase 1 so the ORPC/MCP
- * surface can accept traffic early. But phase 1 CANNOT render: the phase-1 page
- * handler below returns 503 until `setPageHandler` runs at the phase-2 swap. So
- * `/health` reported ready while every page 503'd, the activator believed the
- * wake had landed, and it piped the customer's first request straight into that
- * window — the customer got the 503.
- *
- * Measured 2026-07-31 on quiz-dev/sign-dev: the activator logged `awake` for
- * scala-quiz at 05:58:25.446 and the app logged `GET / 503 3ms` at 05:58:25.452
- * — 6ms later, and 1004ms BEFORE "Swapped from minimal app to full app". Nine
- * such 503s on scala-quiz and two on scala-sign, every one 0-23ms (the
- * placeholder, which does no render work). scala-public logged ZERO, which is
- * the whole reason it looked healthy while the other two did not: the gap is a
- * RACE whose width is the phase-1→phase-2 build time (1420ms cold, 137ms warm),
- * not a config difference between the apps.
- *
- * Gating this on `fullAppReady` makes the signal honest for every consumer at
- * once (the activator's wake gate, `poller-post-restart-health-gate`, any
- * health-gated router) rather than teaching each one its own probe, and it is
- * what `readiness-gated-boot` already requires: "/health returns 503 until
- * ready, 200 after — so it is the real readiness signal", a service being
- * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
- * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
- * a probe of the capability being REQUESTED, never of process existence or of
- * some other surface that happens to answer.
- *
- * The early readiness-gate flip is deliberately left alone: it gates the ORPC
- * tool surface, which genuinely IS usable at phase 1. Only this endpoint, whose
- * one consumer contract is "can you serve me a page", is moved to phase 2.
- */
-export declare function healthHandler(c: Context): Response;
-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

@@ -1,46 +0,0 @@
-/**
- * @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";

package/src/ui-service.d.ts

@@ -1,46 +0,0 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Boots a `kind: "ui"` service. Reads the service_install registry row and
- * orchestrates a fixed pipeline of single-purpose stages onto one Hono app
- * served by @teamscala/service-runtime/serve (one Bun.serve in dev and prod).
- */
-import { Hono } from "hono";
-import type { ServiceInstallConfig } from "./load-service-install-row.ts";
-export interface ResolvedBlock {
-    slug: string;
-    packagePath: string;
-}
-export interface UiServiceBootResult {
-    kind: "ui";
-    blocks: ResolvedBlock[];
-    routes: string[];
-    port: number;
-    app: Hono;
-}
-/**
- * Page-server symbols injected by the caller. service-boot is tier 4
- * (server) and must not import from tier 2 (`@teamscala/service-runtime`)
- * per `installer-and-runtime` Rule 1. The runtime's bin entrypoint
- * boot pipeline imports these from `page-server/` (same package —
- * legal) and passes them down here.
- */
-export interface PageServerDeps {
-    createPageHandler: import("./types.ts").CreatePageHandler;
-}
-/**
- * Boots a UI service using two-phase boot for fast availability.
- *
- * Phase 1 (fast): Build and serve minimal tool-only app (ORPC, data routes,
- * auth gates). This becomes available within ~10s, enabling the MCP tool
- * surface to accept requests immediately after restart.
- *
- * Phase 2 (background): Build full app (pages, hydration) and atomically swap
- * it in. The readiness gate flips to ready after Phase 1, not Phase 2.
- *
- * The interim mitigation (503 + gateway retry + circuit breaker) remains in
- * place and is NOT undone.
- */
-export declare function bootUiService(config: ServiceInstallConfig, serviceSlug: string, deps: PageServerDeps, databaseUrl: string): Promise<UiServiceBootResult>;

package/src/ws-boot-self-test.d.ts

@@ -1,19 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Post-listen WebSocket self-test. Runs after serveStart binds the port.
- * For each declared websocket_routes path, opens a synthetic WebSocket
- * connection and asserts 101 upgrade. Non-101 → BootFatalError.
- *
- * This catches the class of bugs where:
- * - WS route registered after ORPC catch-all (order-dependent 404)
- * - fetchWithPeerPort clones the Request on WS upgrade (breaks Bun.upgrade identity)
- * - websocket_routes config row is stale / missing a handler
- *
- * Runs synchronously after serveStart so the boot aborts before the service
- * reports healthy.
- */
-import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
-export declare function runWsBootSelfTest(config: ServiceInstallConfig, serviceSlug: string, port: number): Promise<void>;