@teamscala/service-boot 0.23.329 → 0.23.331

package/src/read-html-template.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Reads the per-service HTML template (codegen'd from
+ * `@teamscala/scala-install/src/runtime/index.html`) and substitutes the
+ * `{{stylesPath}}` / `{{hydratePath}}` placeholders with the current
+ * content-hashed asset URLs from `dist/client/asset-manifest.json`.
+ *
+ * Build-time produces hashed filenames (e.g. `styles-abc123.css`); the
+ * static-asset handler serves them with `cache-control: immutable`. New
+ * deployments emit new hashes → new URLs → browsers refetch without ever
+ * holding a stale copy. Without the substitution, a fixed
+ * `/assets/styles.css` paired with `immutable` would pin every visitor to
+ * whatever version they first downloaded.
+ *
+ * Cached per service process, keyed on the manifest's mtime. The cache MUST
+ * invalidate when `asset-manifest.json` changes: `buildClientAssets` can
+ * rebuild the bundle AFTER the first request — producing a new content hash,
+ * rewriting the manifest, AND deleting the old hashed bundle
+ * (`removeStaleHashedFiles`). A lifetime-pinned HTML cache then keeps serving
+ * the OLD hash, which now 404s → hydration never runs → the page renders SSR
+ * HTML but is dead client-side (the doc-editor overlay never mounts; scala-docs
+ * 2026-06-13, exposed by the ui-foundation publish-storm's repeated rebuilds).
+ * Re-stat'ing the tiny manifest per request is negligible (OS-cached, no
+ * network); the substituted HTML is reused while the mtime is unchanged.
+ *
+ * NO-SILENT-REVERTS: when the manifest is a TOMBSTONE (the last client build
+ * failed), the served HTML is stamped with a `<meta name="x-client-build-status"
+ * content="failed">` tag in <head> so any operator / chrome-devtools / theme
+ * probe inspecting the page can see the served bundle is STALE (a published fix
+ * that reached node_modules but failed to bundle is silently served from the
+ * prior bundle otherwise — scala-agents 2026-07-18, the white-on-white toolbar
+ * regression that looked "not fixed" while the bundle kept serving pre-fix
+ * bytes across restarts).
+ */
+export declare function readHtmlTemplate(): Promise<string>;

package/src/read-viewport-from-request.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Server-side viewport detection from request headers. Two tiers:
+ * desktop (tablets, laptops, desktops) and mobile (phones).
+ *
+ * Tablets are NOT a separate tier — CSS handles responsive layout
+ * within the desktop tier via flex min/max and @container queries.
+ * Only phones (where the layout is fundamentally single-pane) get
+ * a different server-rendered page.
+ *
+ * Order of authority:
+ * cookie → Sec-CH-UA-Mobile client hint → User-Agent regex → desktop default.
+ */
+export type ViewportTier = "desktop" | "mobile";
+export declare function readViewportFromRequest(request: Request): ViewportTier;

package/src/readiness-gate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Readiness gate — returns 503 + Retry-After: 1 until the boot pipeline
+ * flips the ready flag true as its last step. Registered as the FIRST
+ * middleware in both UI and backend boot paths per readiness-gated-boot.
+ *
+ * The gate fails open: if it ever throws, the request passes through to
+ * the normal handler rather than producing a hard 500.
+ */
+import type { Context, Next } from "hono";
+export declare function isReady(): boolean;
+export declare function setReady(): void;
+export declare function readinessGate(c: Context, next: Next): Promise<Response | void>;

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

@@ -0,0 +1,18 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Walks `service_install.api_routes[]` and binds each entry to its
+ * registered handler (via mountRegistry.handlers, populated by server_packages
+ * during their mount phase). Unresolved handler_slug values are fatal — the
+ * service cannot boot with declared routes pointing at nothing.
+ *
+ * Injects x-remote-port header from Bun's getConnInfo so downstream
+ * handlers (MCP route) can resolve caller identity via process-tree
+ * walking when explicit caller headers are absent.
+ */
+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 registerApiRoutes(app: Hono, config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): number;

package/src/register-crash-handlers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Registers process-level crash handlers (unhandledRejection, uncaughtException)
+ * for a given service. Each handler logs the error with the service slug for
+ * identification. Per constitution crash-isolation.
+ */
+export declare function registerCrashHandlers(opts: {
+    serviceSlug: string;
+}): {
+    unhandledRejection: boolean;
+    uncaughtException: boolean;
+};

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

@@ -0,0 +1,27 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit directly
+ *
+ * Page route registration — reads `page_route` registry rows for the
+ * current service and delegates to `registerRegistryPageRoute`.
+ *
+ * All routes are registry-driven (Phase 1): each `page_route` row pairs
+ * a URL pattern with a `resource_loader` graph that resolves data in
+ * wave-parallel via `resolveFromLoaderConfig`. No deploy-time shell
+ * variant routes — the old `service_install.page_routes[]` Phase 2 path
+ * was removed when every active service migrated to registry-driven
+ * `page_route` rows (all 9 services carry empty arrays).
+ */
+import type { Hono } from "hono";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+import type { RendererComponentEntry } from "./types.ts";
+import type { CreatePageHandler } from "./types.ts";
+export interface RegisterPageRoutesArgs {
+    app: Hono;
+    config: ServiceInstallConfig;
+    components: Record<string, RendererComponentEntry>;
+    serviceSlug: string;
+    createPageHandler: CreatePageHandler;
+}
+export declare function registerPageRoutes(args: RegisterPageRoutesArgs): Promise<string[]>;

package/src/register-page-routes.ts

@@ -17,6 +17,7 @@
 import type { Hono } from "hono";
 import type { ServiceInstallConfig } from "./load-service-install-row.ts";
 import type { RenderModeLiteral } from "./page-route-shell-types.ts";
+import { registerPageServerClient } from "./register-page-server-client.ts";
 import { registerRegistryPageRoute } from "./register-registry-page-route.ts";
 import type { RendererComponentEntry } from "./types.ts";
 import type { CreatePageHandler } from "./types.ts";
@@ -34,6 +35,8 @@ export async function registerPageRoutes(
 ): Promise<string[]> {
 	const { app, config, components, serviceSlug, createPageHandler } = args;
 
+	await registerPageServerClient(serviceSlug);
+
 	const declaredMode = (config as { render_mode?: string }).render_mode;
 	const renderMode: RenderModeLiteral =
 		declaredMode === "portal"

package/src/register-page-server-client.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Registers the system server-client for page-server SSR rendering. Composes
+ * the platform-owned routers into the service's generated `appRouter` and
+ * stashes the resulting client via setServerClient. Called once at boot before
+ * any page route handler fires.
+ */
+export declare function registerPageServerClient(serviceSlug: string): Promise<void>;

package/src/register-registry-page-route/ai-chat-prefetch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SSR-prefetch the signed-in user's AI-chat conversation so a CLICK-opened AI
+ * panel renders the real conversation on first paint — never a loading gate
+ * (ssr-then-live-handoff). The AiChat block lives on the /ai PANEL page, which
+ * isn't rendered when the panel is closed, so its block serverLoader can't run
+ * at page-load; this prefetches server-side (regardless of panel open-state) +
+ * stamps pageData.aiChatSession, which AiChat reads on mount. The agent is
+ * resolved from the /ai panel page's own AiChat block (single source of truth —
+ * no duplicate config to drift). Fired in parallel with the post-processors +
+ * bounded by their window; a failure degrades silently to the client-side
+ * createOrRestore fallback, never an error page.
+ */
+export declare function prefetchAiChatSession(resolved: Record<string, unknown>, sessionUserId: string | undefined, orgId: string | undefined): Promise<Record<string, unknown> | null>;

package/src/register-registry-page-route/graph-cache.d.ts

@@ -0,0 +1,30 @@
+type GraphCache = {
+    getWithMeta(key: string): {
+        value: unknown;
+        stale: boolean;
+    } | undefined;
+    refreshInBackground(key: string, compute: () => Promise<unknown>, opts?: {
+        ttlMs?: number;
+    }): void;
+};
+export declare const staticShellGraphCache: import("@teamscala/cache/cache").ManagedCache<unknown>;
+export declare const paramRouteGraphCache: import("@teamscala/cache/cache").ManagedCache<unknown>;
+/**
+ * Stale-while-revalidate read of a cached loader graph.
+ *
+ * - Fresh hit (within ttlMs): return the cached graph, no refresh.
+ * - Stale hit (within ttlMs + staleTtlMs): return the cached graph AND fire ONE
+ *   background refresh via cache.refreshInBackground — single-flight (deduped
+ *   against the cache's in-flight map), never rejects, leaves the stale entry in
+ *   place on failure. The caller deep-clones the returned value before use.
+ * - Miss (past staleTtlMs, or never cached): return undefined — the caller
+ *   resolves synchronously and cache.set()s the clone.
+ *
+ * The refresh callback must return a graph safe to store. To SKIP caching a
+ * refresh result (e.g. a primary-missing / dead-link graph that must stay
+ * per-request so a just-created record appears immediately), the callback THROWS
+ * — refreshInBackground catches it, leaves the stale entry, and logs one line
+ * (an observable dead-link signal, not a hard error).
+ */
+export declare function readCachedGraph(cache: GraphCache, key: string, refresh: () => Promise<unknown>): unknown | undefined;
+export {};

package/src/register-registry-page-route/meta-title.d.ts

@@ -0,0 +1,2 @@
+export declare function buildMetaFromContext(metaContext: Record<string, Record<string, string>> | undefined, resolved: Record<string, unknown>): Record<string, unknown>;
+export declare function resolveTemplateTitle(service: string, resolved: Record<string, unknown>): string | undefined;

package/src/register-registry-page-route/proposal-approval-email-token.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve the `{{approvalEmail}}` placeholder in a proposal page's button props
+ * (e.g. the Approve CTA) in place. Routing: the organisation's registered
+ * company email FIRST (organisation_profile.contact_email, already resolved
+ * into pageData.brand.contactEmail); the proposal creator's user email only as
+ * a fallback when the org has none — so a cloned proposal can never carry a
+ * stale hard-coded address. The creator lookup is null-safe and adds no user
+ * exposure: it resolves only where the in-process ORPC client exposes `user`
+ * (super-admin), degrading to the org email elsewhere. Called only for proposal
+ * pages; other registry pages are untouched.
+ */
+export declare function applyApprovalEmailToken(pageData: Record<string, unknown>, proposal: {
+    created_by?: string;
+} | undefined): Promise<void>;

package/src/register-registry-page-route/proposal-brand-stamping.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stash a proposal's connected partner logo/colour on `pageData` from the
+ * `partnerOrg` loader source (`crm_organisations` loaded by the proposal's
+ * `partner_id`, via the SAME proven ORPC loader path that loads the proposal
+ * itself). resolve-page-brand (service-runtime) prefers `pageData.partnerLogo`
+ * over any inline body-Hero prop and fans it into the shared `/header` so a
+ * `source: "partner"` OrgLogo fills automatically — the partner logo lives on
+ * the CRM record, never duplicated per proposal. No partner → partnerOrg is
+ * null → nothing set → the partner logo block renders blank. Reading the
+ * already-resolved loader value (not a second hand-rolled getServerClient call)
+ * is what makes this reliable: the earlier direct `crm_organisations.findFirst`
+ * with a Prisma-style object `select` resolved intermittently/never against the
+ * generated ORPC, leaving the header partner blank (2026-06-12).
+ */
+export declare function applyPartnerBrand(pageData: Record<string, unknown>, partnerOrg: {
+    logo_url?: string | null;
+    brand_primary_color?: string | null;
+} | undefined | null): void;
+/**
+ * Auto-resolve the client's company logo from the `clientOrg` loader source
+ * (contact_id → company_id → crm_organisations.logo_url). Injects into the
+ * Hero block's clientLogo prop when it's empty — no manual logo URL needed
+ * per proposal when the contact's company profile has a logo.
+ */
+export declare function applyClientLogo(pageData: Record<string, unknown>, clientOrg: {
+    logo_url?: string | null;
+    name?: string | null;
+} | undefined | null): void;

package/src/register-registry-page-route/resolve-page-data.d.ts

@@ -0,0 +1 @@
+export declare function resolvedToPageData(resolved: Record<string, unknown>, meta: Record<string, unknown>, request: Request, providers: string[] | undefined, regionSlots?: string[], themeOverride?: "light" | "dark"): Record<string, unknown>;

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

@@ -0,0 +1,27 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Reads `page_route` registry rows for the current service slug and registers
+ * Hono routes that resolve data via `resource_loader` graph-based sources.
+ *
+ * Every page_route uses pattern `/:id` and every resource_loader uses a
+ * `sources[]` dependency graph. When header/footer sources are present in
+ * the resolved graph, the output includes a `regions` array for shell rendering.
+ * Otherwise it produces single-page puckData.
+ */
+import type { RenderModeLiteral } from "./page-route-shell-types.ts";
+import type { Hono } from "hono";
+import type { CreatePageHandler, RendererComponentEntry } from "./types.ts";
+interface RegistryRouteArgs {
+    app: Hono;
+    serviceSlug: string;
+    components: Record<string, RendererComponentEntry>;
+    createPageHandler: CreatePageHandler;
+    authMode: string;
+    renderMode: RenderModeLiteral;
+    providers: string[];
+}
+export declare function registerRegistryPageRoute(args: RegistryRouteArgs): Promise<string[]>;
+export {};

package/src/register-static-assets.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Routes every service exposes regardless of registry config: /health
+ * (liveness probe), /favicon.svg (default brand mark), /api/assets/*
+ * (S3 asset proxy), and /assets/* (client bundle + stylesheet produced
+ * by build-client-assets.ts into dist/client/, served identically in
+ * dev and prod per scala-os/ui.md `bun-build-only`).
+ */
+import type { Hono } from "hono";
+export declare function registerStaticAssets(app: Hono, serviceSlug: string, brandOrg?: string): Promise<void>;

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-brand-favicon.ts

@@ -55,7 +55,7 @@ export async function resolveBrandFaviconPath(
  * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
  * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
  * store takes 6s locally / up to 21s in prod, and the in-process cache resets
- * on every restart (deploys, dep-sync). Without warming, the first
+ * 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.
  */

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-service-port.d.ts

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

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>;