@teamscala/service-boot 0.23.284 → 0.23.286

package/src/page-server-orpc/puck-pages-router.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for loading Puck pages. These replace the direct Prisma calls
+ * in load-puck-page-by-slug.ts with proper ORPC procedures that receive
+ * context.prisma from the router.
+ */
+import * as v from "valibot";
+export declare const puckPagesRouter: {
+    loadFromWebsite: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly websiteSlug: v.StringSchema<undefined>;
+        readonly path: v.StringSchema<undefined>;
+    }, undefined>, v.NullableSchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly path: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly puckData: v.UnknownSchema;
+        readonly mode: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly render_mode: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly website_slug: v.StringSchema<undefined>;
+        readonly organisation_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly meta_title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly meta_description: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly website: v.ObjectSchema<{
+            readonly slug: v.StringSchema<undefined>;
+            readonly name: v.StringSchema<undefined>;
+            readonly organisation_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly website_type: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly layout_settings: v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+            readonly header_settings: v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+            readonly footer_settings: v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+    loadById: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly pageId: v.StringSchema<undefined>;
+    }, undefined>, v.NullableSchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly path: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly puckData: v.UnknownSchema;
+        readonly mode: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly render_mode: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly website_slug: v.StringSchema<undefined>;
+        readonly organisation_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly meta_title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly meta_description: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly website: v.ObjectSchema<{
+            readonly slug: v.StringSchema<undefined>;
+            readonly name: v.StringSchema<undefined>;
+            readonly organisation_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly website_type: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly layout_settings: v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+            readonly header_settings: v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+            readonly footer_settings: v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+};
+export type PuckPagesRouter = typeof puckPagesRouter;

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

@@ -0,0 +1,16 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Server-side ORPC client for in-process direct invocation, per the canonical
+ * Vite/Next/Nuxt SSR pattern documented at https://orpc.dev/docs/best-practices/optimize-ssr
+ *
+ * The host service (scala-install) must call `setServerClient(client)` once
+ * at boot, after createRouterClient(appRouter, { context: { prisma } }).
+ * Then page-server's createPageHandler reads `getServerClient()` per request
+ * — no HTTP loopback, just a typed function call.
+ */
+import { createRouterClient } from "@orpc/server";
+export declare function getServerClient(): ReturnType<typeof createRouterClient>;
+export declare function setServerClient(client: ReturnType<typeof createRouterClient>): void;

package/src/page-server-orpc/templates-router.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedure: templates.getSettings(slug). Reads the registry_entries row
+ * of type='template_settings' for the requested slug, validates against the
+ * matching Valibot schema from db-validation, returns typed settings.
+ *
+ * Per data-access.md: every data read goes through ORPC. The Template
+ * components do not call Prisma or registry directly — they receive the
+ * typed result of this procedure as a prop.
+ *
+ * Server-side (SSR) calls land here in-process via createRouterClient.
+ * Client-side calls would land here over HTTP via createORPCClient.
+ */
+import * as v from "valibot";
+export declare const templatesRouter: {
+    getSettings: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly slug: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<unknown, unknown>, Record<never, never>, Record<never, never>>;
+    /**
+     * Patch a template's settings row. The patch is a deep partial applied
+     * over the existing config; the merged result is validated against the
+     * matching Valibot schema before write. Used by chrome layout (pane
+     * widths, toolbar height, etc.) so resizes persist server-side and the
+     * next SSR render picks them up directly — no localStorage, no flash.
+     */
+    updateSettings: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly slug: v.StringSchema<undefined>;
+        readonly patch: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<unknown, unknown>, Record<never, never>, Record<never, never>>;
+};
+export type TemplatesRouter = typeof templatesRouter;

package/src/page-server-orpc/user-preferences-router.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for per-user portal UI preferences (sidebar collapse,
+ * panel sizes, active right panel, conversation ID, brand cache).
+ * Reads and writes the `portal` key inside `user.preferences` JSONB.
+ *
+ * The SSR page loads initial state via getPortalPreferences; mutations
+ * from usePortalActionHelpers call updatePortalPreferences. This replaces
+ * the injected localStorage pattern with DB-backed persistence.
+ */
+import * as v from "valibot";
+export declare const userPreferencesRouter: {
+    /**
+     * Read the current user's portal preferences from user.preferences.portal.
+     * Returns null portal if no preferences exist yet.
+     */
+    getPortalPreferences: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        portal: null;
+    } | {
+        portal: Record<string, unknown>;
+    }, {
+        portal: null;
+    } | {
+        portal: Record<string, unknown>;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * Merge and persist a patch to the user's portal preferences.
+     * The patch is a deep partial of the portal object; missing keys
+     * are preserved from the existing value.
+     */
+    updatePortalPreferences: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly patch: v.ObjectSchema<{
+            readonly theme: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["light", "dark"], undefined>, undefined>, undefined>;
+            readonly paneLeftWidth: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly paneRightWidth: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly sidebarCollapsed: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly activePanel: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly panelSizes: v.OptionalSchema<v.ObjectSchema<{
+                readonly main: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+                readonly right: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            }, undefined>, undefined>;
+            readonly conversationId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly brandCache: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
+                readonly logo: v.ObjectSchema<{
+                    readonly light: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                    readonly dark: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                    readonly brand: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                }, undefined>;
+                readonly primaryColor: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, undefined>, undefined>;
+        }, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        portal: {
+            theme?: "dark" | "light" | null | undefined;
+            paneLeftWidth?: number | undefined;
+            paneRightWidth?: number | undefined;
+            sidebarCollapsed?: boolean | undefined;
+            activePanel?: string | null | undefined;
+            conversationId?: string | null | undefined;
+            panelSizes: unknown;
+            brandCache: unknown;
+        };
+    }, {
+        portal: {
+            theme?: "dark" | "light" | null | undefined;
+            paneLeftWidth?: number | undefined;
+            paneRightWidth?: number | undefined;
+            sidebarCollapsed?: boolean | undefined;
+            activePanel?: string | null | undefined;
+            conversationId?: string | null | undefined;
+            panelSizes: unknown;
+            brandCache: unknown;
+        };
+    }>, Record<never, never>, Record<never, never>>;
+};
+export type UserPreferencesRouter = typeof userPreferencesRouter;

package/src/pg-boss-handler-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The pg-boss scheduled-job handler registry — `handler_slug` → handler
+ * function. Built on `@teamscala/generic-registry` `createRegistry` (the mandated
+ * primitive per `generic-registry-is-the-only-registry-pattern`); a hand-rolled
+ * Map or a hardcoded switch in service-boot is the prohibited alternative.
+ *
+ * Handlers live in packages and self-register at boot (a boot hook / package
+ * subscriber shape) by calling `registerScheduledJobHandler`. `resolveHandler`
+ * in `pg-boss-mount.ts` reads this registry to dispatch a firing `scheduled_job`
+ * row to its registered function.
+ */
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+export type PgBossJobHandler = (ctx: {
+    config: ScheduledJobConfig;
+}) => Promise<void> | void;
+export declare const pgBossHandlerRegistry: any;
+/**
+ * Register a handler for a `scheduled_job.handler_slug`. Idempotent on re-import
+ * (createRegistry.register overwrites silently — last registration wins).
+ */
+export declare function registerScheduledJobHandler(slug: string, handler: PgBossJobHandler): void;

package/src/pg-boss-mount.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Mounts pg-boss for a backend service. Reads all scheduled_job registry
+ * entries scoped to the current service from the registry cache, registers
+ * pg-boss workers per queue_name, and schedules cron/interval jobs.
+ * Per Constitution Rule 6: pg-boss is the single mechanism for all
+ * application background work.
+ */
+import { PgBoss } from "pg-boss";
+import "./handlers/prune-stale-data.ts";
+import "./handlers/projects-digest.ts";
+import "./handlers/sweep-event-log.ts";
+import "./handlers/sweep-host-cache.ts";
+import "./handlers/bun-stable-watch.ts";
+import "./handlers/whatsapp-liveness.ts";
+import "./handlers/upstream-issue-sync.ts";
+import "./handlers/scheduled-browser-tests.ts";
+import "./handlers/scala-tools-currency-watch.ts";
+import "./handlers/registry-stale-inactive-sweep.ts";
+export interface PgBossMountContext {
+    databaseUrl: string;
+    serviceSlug: string;
+    packages: string[];
+}
+export interface MountedJob {
+    queueName: string;
+    handlerSlug: string;
+    cron?: string;
+    intervalSeconds?: number;
+}
+export interface PgBossMountResult {
+    boss: PgBoss | null;
+    jobs: MountedJob[];
+}
+export declare function intervalToCron(intervalSeconds: number): string;
+export declare function mountPgBoss(ctx: PgBossMountContext): Promise<PgBossMountResult>;

package/src/proposal-authorized-emails.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Resolves the set of emails authorized to view a proposal. A proposal is
+ * gated (proposal-access) — only these emails can unlock it:
+ *
+ *   - the issuing-org team: every member of the proposal's organisation
+ *     (better_auth_member → user.email). Lets the agency team open any of their
+ *     own proposals AND covers existing proposals whose created_by is
+ *     "system"/null.
+ *   - the recipient: the proposal's CRM contact (client_database.primary_email),
+ *     when contact_id is set.
+ *   - the partner team: every CRM contact belonging to the proposal's partner
+ *     org (client_database.company_id = proposals.partner_id → primary_email),
+ *     when partner_id is set. Lets the co-delivery partner's team open a
+ *     co-branded proposal. The partner is still branding-first; this is the one
+ *     access edge it carries.
+ *
+ * Uses $queryRaw (raw SQL) deliberately: the per-service Prisma client is scoped
+ * to that service's own models, so the proposals service's client has no
+ * `member`/`user` model methods — but $queryRaw runs against the shared DB
+ * regardless of the client's model scope. Returns a lowercased Set, checked
+ * server-side only (emails never sent to the client). Fail-closed: any error
+ * yields an empty set (no access).
+ */
+export declare function resolveProposalAuthorizedEmails(proposalId: string): Promise<Set<string>>;

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

@@ -0,0 +1,17 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Injects the ProposalChatLauncher block into an AUTHORISED proposal page (called
+ * from proposalGateConfig.onAuthorized — so the bubble lives strictly behind the
+ * email gate, and every proposal gets it with no per-page Puck edit). It builds
+ * the proposal's full 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
+ * "Proposal Assistant" agent answers about whichever proposal is being viewed.
+ *
+ * The agent id is config, not code (registries-are-source-of-truth): the
+ * `config / proposal-assistant-agent` row carries { agentId }. No row (or no
+ * agent) → no injection, the page renders exactly as before (fail-soft).
+ */
+export declare function injectProposalChatLauncher(resolved: Record<string, unknown>, viewerEmail: string): Promise<void>;

package/src/proposal-gate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The PROPOSAL content gate, expressed as config for the content-gate primitive
+ * (content-gate/). No bespoke gate plumbing — just the proposal-specific bits:
+ * which resource (resolved.proposal.id), who's authorized (issuing-org team +
+ * recipient), what to seed (initialVisitor for the chat), and how to withhold
+ * (replace the proposal body with an injected SignIn gate block + neutralize the
+ * meta tags). The engine handles cookie/token/verify/orchestration.
+ *
+ * Universal: every proposal route exposes resolved.proposal, so this gates every
+ * proposal (existing + new) with no per-page block or migration.
+ */
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+export declare const proposalGateConfig: ContentGateConfig;
+export declare const proposalAccessConfig: AccessConfig;

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-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: any;
+export declare const paramRouteGraphCache: any;
+/**
+ * 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>;