@teamscala/service-boot 0.23.329 → 0.23.331

package/src/install-logging.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * One-call install of the entire logging pipeline. After installLogging()
+ * runs, every error in the service — process-level, HTTP middleware, Hono
+ * handlers, Puck blocks, even third-party packages calling console.* — is
+ * captured by @teamscala/logger and flows to Sentry/GlitchTip (prod) or
+ * loga (dev) with full context. Application code never imports the logger
+ * or wraps anything in try/catch for telemetry purposes.
+ *
+ * Marked @indivisible-unit: installLogging (early bootstrap, hardcoded
+ * defaults) and applyLoggerConfig (late-stage, DB-driven) are the two
+ * phases of the same one-call install — the service boot pipeline calls
+ * them in sequence with the same serviceSlug.
+ */
+import { attachRequestLogger } from "@teamscala/logger/install-logging";
+export { attachRequestLogger };
+export interface InstallLoggingOptions {
+    serviceSlug: string;
+}
+/** Initial bootstrap install — runs BEFORE DB/Registry are available.
+ *  Uses hardcoded defaults (INFO level, /tmp/scala-logs). */
+export declare function installLogging(opts: InstallLoggingOptions): void;
+/** Late-stage configuration — runs AFTER Registry is loaded.
+ *  Injects DB-driven settings into the logger primitive. */
+export declare function applyLoggerConfig(config: {
+    minLevel?: "debug" | "info" | "warn" | "error";
+    logDir?: string;
+    maxFileSize?: number;
+    maxFiles?: number;
+}): void;

package/src/load-service-install-row.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Loads the service_install registry row for a given service slug.
+ * Uses registry.require() per Constitution Rule 11.
+ * Schema is owned by @teamscala/db-validation (Rule 7).
+ */
+import type { ServiceInstallConfig } from "@teamscala/db-validation/registry-schemas/service-install";
+export { ServiceInstallConfigSchema } from "@teamscala/db-validation/registry-schemas/service-install";
+export type { ServiceInstallConfig };
+export interface LoadServiceInstallRowResult {
+    success: true;
+    config: ServiceInstallConfig;
+}
+export interface LoadServiceInstallRowError {
+    success: false;
+    error: "row_not_found" | "validation_failed";
+    slug: string;
+    message: string;
+}
+export type LoadServiceInstallRowOutcome = LoadServiceInstallRowResult | LoadServiceInstallRowError;
+export declare function loadServiceInstallRow(serviceSlug: string): Promise<LoadServiceInstallRowOutcome>;

package/src/load-service-prisma-client.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Loads the service's own generated PrismaClient from
+ * <cwd>/prisma/generated/prisma/client.ts. Each service repo generates its own
+ * client from its own schema.prisma; resolving a static import would pick up
+ * whichever @prisma/generated bun resolves first in a multi-service workspace,
+ * which is wrong.
+ *
+ * No fallback: if the generated client is missing the deploy is broken — fail
+ * loud with the remediation step.
+ */
+export type ServicePrismaClientConstructor = new (args: {
+    adapter: unknown;
+}) => unknown;
+export declare function loadServicePrismaClient(serviceSlug: string): Promise<ServicePrismaClientConstructor>;

package/src/mount-orpc-router.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Mounts the composed ORPC app router (generated Prisma CRUD + custom fn routers)
+ * at /api/rpc/* over HTTP via @orpc/server/fetch's RPCHandler.
+ * Uses getAppRouter() from @teamscala/orpc/app-router which merges generated
+ * routers with custom routers registered via registerCustomRouter().
+ */
+import type { Hono } from "hono";
+export interface OrpcMountResult {
+    routeCount: number;
+}
+export declare function mountOrpcRouter(app: Hono, serviceSlug: string): Promise<OrpcMountResult | null>;

package/src/mount-orpc-router.ts

@@ -37,7 +37,7 @@ export async function mountOrpcRouter(
 	);
 
 	// No generated ORPC router is the EXPECTED state for daemon-only / boot-hook
-	// services (session-picker, dep-sync, etc.) that own no DB schema or
+	// services (session-picker, package-poller, etc.) that own no DB schema or
 	// api_routes — they serve no /api/rpc surface. Skip silently: importing a
 	// nonexistent module would throw into the catch below and surface a
 	// misleading "ORPC router not mounted" WARN on every boot. The catch is

package/src/mount-server-packages.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Walks `service_install.server_packages[]`, dynamic-imports each, and calls
+ * its `mount(ctx)` function. Server packages register handlers / boot hooks /
+ * scheduled jobs / WS routes via the MountContext exposed in ctx; the
+ * resulting MountRegistry is consumed by register-api-routes /
+ * register-ws-routes / run-boot-hook-list / start-scheduled-jobs.
+ */
+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";
+/**
+ * Speculatively import every server_package's mount module so Bun compiles
+ * the module graphs into its cache NOW, overlapping the (CPU-bound)
+ * compilation with whatever I/O the caller runs next. When mountServerPackages
+ * later imports the same paths they hit the cache (instant).
+ *
+ * Same pattern as create-boot-pipeline's speculative preloads — the
+ * cross-internet DB I/O in the gate chain (~3.4s) is dead time the compiler
+ * can use. Best-effort + non-fatal: a failed import here (wrong candidate
+ * path, transient resolution race) is silently swallowed because
+ * mountServerPackages will re-attempt with full error surfacing; the preload
+ * only warms the cache, never gates boot.
+ */
+export declare function preloadServerPackages(packages: string[]): Promise<void>;
+export declare function mountServerPackages(app: Hono, config: ServiceInstallConfig, serviceSlug: string): Promise<MountRegistry>;

package/src/mount.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Server-package mount for opt-in service-boot watchdogs.
+ */
+import type { MountContext } from "@teamscala/os/runtime-contracts/mount-context";
+export declare function mount(ctx: MountContext): void;

package/src/mutable-app-ref.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Mutable app reference for two-phase boot. Allows swapping the Hono app
+ * atomically after building the full app in the background. The initial app
+ * is a minimal tool-only surface (ORPC, data routes) that starts serving
+ * immediately; the full app (pages, hydration) is built off-to-the-side and
+ * swapped in once complete.
+ *
+ * Thread-safety: Bun is single-threaded, so a simple module-level variable
+ * is sufficient. Atomics are not needed.
+ */
+import type { Hono } from "hono";
+/**
+ * Create a new mutable app reference initialized with the provided app.
+ * This should be called once at boot time.
+ */
+export declare function initMutableAppRef(initialApp: Hono, label: string): void;
+/**
+ * Get the current app. Throws if the ref hasn't been initialized.
+ */
+export declare function getApp(): Hono;
+/**
+ * Get the current app label for logging.
+ */
+export declare function getAppLabel(): string;
+/**
+ * Atomically swap the app to a new instance. This is called after the
+ * full app is built in the background. Returns the previous label for logging.
+ */
+export declare function swapApp(newApp: Hono, newLabel: string): string;
+/**
+ * Fetch handler that routes through the mutable app reference.
+ * This replaces the direct app.fetch call in the serve layer.
+ *
+ * Stamps transport-derived identity (x-caller-remote-address/-port + the
+ * loopback local-caller comm) via the SAME stampTransportIdentity helper as
+ * direct mode, so two-phase-boot (mutable-ref) UI services carry identical
+ * identity on every request — closing the gap where the mutable-ref path
+ * previously served requests with no transport headers stamped at all.
+ */
+export declare function fetchWithMutableApp(req: Request, server: ReturnType<typeof Bun.serve>): Promise<Response>;

package/src/page-route-shell-types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Render mode literal shared across page route registration. The old
+ * shell-variant types (LegacyShell, PageSlugShell, RegionsShell,
+ * PublicShell, ConfigPageRoute) were removed when the Phase 2 deploy-time
+ * `service_install.page_routes[]` path was eliminated — all routing is
+ * now registry-driven `page_route` rows (Phase 1).
+ */
+export type RenderModeLiteral = "public" | "portals" | "utility";

package/src/page-server-orpc/audit-revert-router.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Audit revert procedure — re-applies an audit_trail row's changes_before to
+ * the entity via the canonical generated Prisma procedure for the entity's
+ * table: INSERT→delete the created row, UPDATE→restore the old values,
+ * DELETE→recreate from the deleted snapshot. The revert write itself fires the
+ * audit extension + DB trigger, recording a NEW forward audit_trail row —
+ * history is never edited (audit-trail-permanent; the undo is itself audited).
+ *
+ * Gated to super-admin (reverting business data is privileged). The caller
+ * must pass the audit_trail row id; the procedure resolves table + action +
+ * before-snapshot from that row.
+ */
+import * as v from "valibot";
+export declare const auditRevertRouter: {
+    /**
+     * Revert a single audited change by re-applying changes_before through the
+     * generated Prisma model for the entity's table. Returns the action taken.
+     */
+    revert: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly auditTrailId: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        success: true;
+        action: string;
+        table: string;
+        entityId: string;
+    }, {
+        success: true;
+        action: string;
+        table: string;
+        entityId: string;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export type AuditRevertRouter = typeof auditRevertRouter;

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

@@ -0,0 +1,12 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Module-level singleton for the hub MCP client. setHubMcpClient(client)
+ * is called once at boot by the host service after creating the multi-
+ * tenant MCP client; createPageHandler's resolve-page-state reads it via
+ * getHubMcpClient to pass through to data loaders.
+ */
+export declare function setHubMcpClient(client: unknown): void;
+export declare function getHubMcpClient(): unknown | undefined;

package/src/page-server-orpc/portal-diagnostics-router.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for portal diagnostics. These replace direct Prisma calls
+ * in the portal diagnostic section files with proper ORPC procedures that
+ * receive context.prisma from the router.
+ */
+import * as v from "valibot";
+export declare const portalDiagRouter: {
+    findPortalWebsite: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{}, undefined>, v.NullableSchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly name: v.StringSchema<undefined>;
+        readonly organisation_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+    findMember: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly organisationId: v.StringSchema<undefined>;
+    }, undefined>, v.NullableSchema<v.ObjectSchema<{
+        readonly user_id: v.StringSchema<undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+    countPages: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly websiteId: v.StringSchema<undefined>;
+    }, undefined>, v.NumberSchema<undefined>, Record<never, never>, Record<never, never>>;
+    findPages: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly websiteId: v.StringSchema<undefined>;
+        readonly path: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly take: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly orderBy: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly path: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly name: v.StringSchema<undefined>;
+        readonly puck_data: v.UnknownSchema;
+        readonly updated_at: v.StringSchema<undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+    findBlockSchemas: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly slugs: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ArraySchema<v.ObjectSchema<{
+        readonly slug: v.StringSchema<undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+    findWebsites: import("@orpc/server").DecoratedProcedure<Record<never, never>, Record<never, never>, v.ObjectSchema<{
+        readonly take: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    }, undefined>, v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly name: v.StringSchema<undefined>;
+    }, undefined>, undefined>, Record<never, never>, Record<never, never>>;
+};
+export type PortalDiagRouter = typeof portalDiagRouter;

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,27 @@
+/**
+ * @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;
+    /** Per-job data payload from a one-shot `boss.send()` — absent for scheduled jobs. */
+    jobData?: unknown;
+}) => Promise<unknown> | unknown;
+export declare const pgBossHandlerRegistry: import("@teamscala/generic-registry/create-registry").Registry<PgBossJobHandler>;
+/**
+ * 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,42 @@
+/**
+ * @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/scala-tools-currency-watch.ts";
+import "./handlers/singleton-tools-currency-watch.ts";
+import "./handlers/registry-stale-inactive-sweep.ts";
+import "./handlers/pane-outbox-drain.ts";
+/** Returns the mounted PgBoss instance, or null if pg-boss is not running on this service. */
+export declare function getPgBoss(): PgBoss | null;
+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;