@teamscala/service-boot 0.23.284

package/src/fn-routers/chat-session-router.ts

@@ -0,0 +1,455 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for the AUTHENTICATED AI-chat conversation lifecycle —
+ * the org+user-keyed sibling of publicGptSessionRouter (which is contact-
+ * linked for anonymous public GPT visitors). One signed-in user chatting
+ * with one agent in one org owns a thread of `conversations` rows; this
+ * router createOrRestore-s the active one, saves turns, archives+news on
+ * clear, lists past threads, and loads a specific thread.
+ *
+ * Identity: the USER is resolved from the ORPC session context (`authed`
+ * middleware → `context.user.id`); the ORGANISATION is supplied by the
+ * client (it is the URL :orgId for org-scoped apps like scala-projects —
+ * the session does not carry it) and VERIFIED — the caller must be a
+ * member of that organisation, else FORBIDDEN. A caller cannot read or
+ * write another user's threads (ownership is user_id) or another org's
+ * (createOrRestore/list are membership-scoped to the supplied org).
+ *
+ * This restores the capability the portal AI chat lost when the June
+ * chat-engine migration severed `usePortalConversationId` + the
+ * `portalConversation` router (capability-named `chatSession` here per
+ * name-by-capability; the host-named orphan was deleted in the same change).
+ *
+ * Persistence model: the chat client owns writes via onMessagesPersist →
+ * saveMessages, and sends clientPersists:true so handle-chat-stream skips its
+ * own persistChatRun (single writer, no double-persist). Verbatim UIMessage
+ * parts are stored in messages.channel_data.parts so multi-step (tool-using)
+ * turns round-trip losslessly (apps/chat.md messages-stored-as-uimessage-verbatim).
+ */
+
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { authed, type Context } from "./auth-router.ts";
+import { persistChatMessages } from "./persist-chat-messages.ts";
+
+/** channel_data discriminator carrying the agent this thread belongs to. */
+const assistantType = (agentId: string) => `chat:${agentId}`;
+
+/**
+ * How many recent messages createOrRestore returns. The full history was
+ * previously loaded (unbounded) — a heavy thread paid ~2.5s + ~460KB on every
+ * open/prefetch. Older messages paginate via `loadEarlier`. Adjustable; when a
+ * tunable, lift to a registry config row (config-constants-db-driven).
+ */
+const RECENT_MESSAGE_LIMIT = 50;
+
+const createOrRestoreSchema = v.object({
+	agentId: v.string(),
+	organisationId: v.string(),
+	/**
+	 * SSR-only: the real user's id, passed by the AiChat serverLoader. The
+	 * in-process server client is system-authed (context.user.id === "system"),
+	 * so without this the conversation is created under user_id="system" and
+	 * the real user's saveMessages hits assertOwns → FORBIDDEN. Only honoured
+	 * when the caller is the system user (server-side SSR), never from a
+	 * client-side ORPC call.
+	 */
+	userId: v.optional(v.string()),
+});
+const loadSchema = v.object({
+	conversationId: v.string(),
+});
+const saveMessagesSchema = v.object({
+	conversationId: v.string(),
+	messages: v.array(
+		v.object({
+			// The SDK UIMessage id — persisted AS the row PK so a reload/retry/
+			// dual-write upserts the SAME row instead of inserting a duplicate
+			// (chat-message-ids-server-stable). The duplicate truncated-assistant
+			// rows came from create-without-id: each save inserted a fresh row the
+			// next save could never reconcile against.
+			id: v.optional(v.string()),
+			role: v.string(),
+			content: v.string(),
+			// Verbatim UIMessage parts (messages-stored-as-uimessage-verbatim).
+			parts: v.optional(v.array(v.any())),
+			// UIMessage metadata — per-message token usage (inputTokens/
+			// outputTokens/contextWindow) the stream attaches; persisted so the
+			// context-usage gauge rehydrates on reload (was dropped before).
+			metadata: v.optional(v.record(v.string(), v.any())),
+		}),
+	),
+});
+const clearSchema = v.object({
+	conversationId: v.string(),
+});
+const listSchema = v.object({
+	agentId: v.string(),
+	organisationId: v.string(),
+});
+const loadEarlierSchema = v.object({
+	conversationId: v.string(),
+	/** Cursor: the occurred_at (ISO) of the oldest currently-loaded message. */
+	before: v.pipe(
+		v.string(),
+		v.isoTimestamp(),
+	),
+	/** Cap; defaults to RECENT_MESSAGE_LIMIT, clamped to it. */
+	limit: v.optional(v.number()),
+});
+
+interface SessionUser {
+	id: string;
+	name?: string | null;
+	email?: string;
+}
+
+async function throwForbidden(message: string): Promise<never> {
+	const { ORPCError } = await import("@orpc/server");
+	throw new ORPCError("FORBIDDEN", { message });
+}
+
+/**
+ * Reject if the conversation does not belong to the calling user. Ownership
+ * by user_id is the complete proof (the row was created with this user's id);
+ * no org check needed.
+ */
+async function assertOwns(
+	prisma: any,
+	conversationId: string,
+	user: SessionUser,
+): Promise<any> {
+	const conv = await prisma.conversations.findUnique({
+		where: { id: conversationId },
+	});
+	if (!conv || conv.user_id !== user.id) await throwForbidden("Conversation not found.");
+	return conv;
+}
+
+/** Map stored message rows to the wire shape the chat client restores. */
+function mapMessages(msgs: any[]) {
+	return msgs
+		.filter((m: any) => m.role === "user" || m.role === "assistant")
+		.map((m: any) => ({
+			// Restore the stable row id so the client re-seeds useChat with the
+			// SAME ids it persisted — a later re-save then upserts instead of
+			// duplicating (chat-message-ids-server-stable).
+			id: m.id,
+			role: m.role,
+			content: m.content,
+			parts: (m.channel_data as { parts?: unknown[] } | null)?.parts,
+			// Restore the per-message token usage so the context-usage gauge can
+			// recompute on reload (the stream attaches it as UIMessage metadata).
+			metadata: (m.channel_data as { metadata?: Record<string, unknown> } | null)?.metadata,
+			created_at: m.created_at,
+			// The ordering field — exposed so the client can pass the oldest
+			// loaded message's occurred_at as the loadEarlier cursor.
+			occurred_at: m.occurred_at,
+		}));
+}
+
+export const chatSessionRouter = {
+	// createOrRestore — resume the caller's most-recent ACTIVE thread for this
+	// agent in the supplied (membership-verified) org, else reactivate the
+	// most-recent archived one, else create a new empty thread. Mirrors
+	// publicGptSession.createOrRestore's restore logic but keyed on
+	// (org, user_id, assistant_type) instead of contact_email.
+	createOrRestore: authed
+		.input(createOrRestoreSchema)
+		.handler(async ({ input, context }) => {
+			const { agentId, organisationId: orgId, userId: overrideUserId } = input;
+			const prisma = (context as Context).prisma;
+			const ctxUser = context.user as SessionUser;
+			// SSR serverLoader override: when the caller is the system user AND a
+			// real userId is provided, use that instead — so the conversation is
+			// created under the real user's identity, not "system".
+			const effectiveUserId =
+				ctxUser.id === "system" && overrideUserId ? overrideUserId : ctxUser.id;
+			const user = { ...ctxUser, id: effectiveUserId };
+			const log = getAppLogger();
+			const aType = assistantType(agentId);
+
+			try {
+				// Resolve the agent's configured model so the chat footer can show
+				// it next to the session ID ("Session ID · <model>"). ai_model is
+				// the agent's model key (e.g. "FLASH"), mapped to an llm_model row.
+				const agent = await prisma.ai_agents.findUnique({
+					where: { id: agentId },
+					select: { ai_model: true },
+				});
+				const model = agent?.ai_model ?? null;
+				const candidates = await prisma.conversations.findMany({
+					where: {
+						channel: "ai",
+						organisation_id: orgId,
+						user_id: user.id,
+						channel_data: { path: ["assistant_type"], equals: aType },
+					},
+					orderBy: { created_at: "desc" },
+				});
+
+				let existing: any =
+					candidates.find((c: any) => c.status === "active") ?? null;
+				// A returning user whose only thread is archived → reactivate the
+					// most-recent one so their history continues (matches the GPT
+					// "session gone" fix).
+				if (!existing && candidates.length > 0) {
+					existing = candidates[0];
+					await prisma.conversations.update({
+						where: { id: existing.id },
+						data: { status: "active" },
+					});
+				}
+
+				if (existing) {
+					// Bound to the most-recent RECENT_MESSAGE_LIMIT messages so a heavy
+					// thread doesn't pay ~2.5s + ~460KB on every open/prefetch (the
+					// prior unbounded load). Older messages paginate via `loadEarlier`.
+					// desc+take N+1, then reverse → asc for display; take N+1 detects
+					// whether older rows exist (hasMore drives the load-more control).
+					const recentRows = await prisma.messages.findMany({
+						where: { conversation_id: existing.id },
+						orderBy: { occurred_at: "desc" },
+						take: RECENT_MESSAGE_LIMIT + 1,
+					});
+					const hasMore = recentRows.length > RECENT_MESSAGE_LIMIT;
+					const windowRows = hasMore
+						? recentRows.slice(0, RECENT_MESSAGE_LIMIT)
+						: recentRows;
+					const msgs = windowRows.reverse();
+					const cd = (existing.channel_data ?? {}) as Record<
+						string,
+						unknown
+					>;
+					return {
+						conversationId: existing.id,
+						model,
+						messages: mapMessages(msgs),
+						tokenTotals: {
+							inputTokens: (cd.total_input_tokens as number) ?? 0,
+							outputTokens: (cd.total_output_tokens as number) ?? 0,
+						},
+						hasMore,
+					};
+				}
+
+				const conversation = await prisma.conversations.create({
+					data: {
+						channel: "ai",
+						organisation_id: orgId,
+						user_id: user.id,
+						title: "New chat",
+						status: "active",
+						channel_data: {
+							assistant_type: aType,
+							source: "authed-chat",
+							total_input_tokens: 0,
+							total_output_tokens: 0,
+						},
+						...(user.name || user.email
+							? {
+									members: {
+										name: user.name ?? null,
+										email: user.email ?? null,
+									},
+								}
+							: {}),
+					},
+				});
+
+				return {
+					conversationId: conversation.id,
+					model,
+					messages: [],
+					tokenTotals: { inputTokens: 0, outputTokens: 0 },
+					hasMore: false,
+				};
+			} catch (err) {
+				log.error(
+					`[chatSession.createOrRestore] failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+				throw err;
+			}
+		}),
+
+	// loadEarlier — paginate OLDER messages for a thread (the recent-N window
+	// createOrRestore returns is complemented by this). Cursor-based on
+	// occurred_at (the ordering field) so a new message appended at the tail
+	// never shifts the older window. Ownership is user_id (assertOwns).
+	loadEarlier: authed
+		.input(loadEarlierSchema)
+		.handler(async ({ input, context }) => {
+			const prisma = (context as Context).prisma;
+			const user = context.user as SessionUser;
+			const limit = Math.min(
+				input.limit ?? RECENT_MESSAGE_LIMIT,
+				RECENT_MESSAGE_LIMIT,
+			);
+			await assertOwns(prisma, input.conversationId, user);
+			const olderRows = await prisma.messages.findMany({
+				where: {
+					conversation_id: input.conversationId,
+					occurred_at: { lt: new Date(input.before) },
+				},
+				orderBy: { occurred_at: "desc" },
+				take: limit + 1,
+			});
+			const hasMore = olderRows.length > limit;
+			const windowRows = hasMore ? olderRows.slice(0, limit) : olderRows;
+			const msgs = windowRows.reverse();
+			return { messages: mapMessages(msgs), hasMore };
+		}),
+
+	// saveMessages — the onMessagesPersist writer. Stamps occurred_at with a
+	// 1ms step preserving array order (created_at is the DB backstop) and
+	// stores verbatim UIMessage parts in channel_data.parts. Reuses the GPT
+	// saveMessages shape. Ownership is user_id (assertOwns).
+	saveMessages: authed
+		.input(saveMessagesSchema)
+		.handler(async ({ input, context }) => {
+			const prisma = (context as Context).prisma;
+			const user = context.user as SessionUser;
+			const conv = await assertOwns(prisma, input.conversationId, user);
+			const orgId = conv.organisation_id;
+
+			// The write itself lives in ONE shared surface (persist-chat-messages);
+			// this router only resolves identity (assertOwns by user_id) above.
+			await persistChatMessages(prisma, {
+				conversationId: input.conversationId,
+				organisationId: orgId,
+				messages: input.messages,
+			});
+			return { success: true };
+		}),
+
+	// clear = START FRESH. Archive the old thread + drop its (now-cleared)
+	// messages so it never auto-restores, AND create a brand-new empty thread
+	// for the same user+org+agent with a NEW id (deterministic, no reload).
+	// Mirrors publicGptSession.clear. Ownership is user_id (assertOwns).
+	clear: authed.input(clearSchema).handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma;
+		const user = context.user as SessionUser;
+		const log = getAppLogger();
+
+		const old = await assertOwns(prisma, input.conversationId, user);
+
+		await prisma.messages.deleteMany({
+			where: { conversation_id: input.conversationId },
+		});
+		await prisma.conversations.update({
+			where: { id: input.conversationId },
+			data: { status: "archived" },
+		});
+
+		const cd = (old.channel_data ?? {}) as Record<string, unknown>;
+		const conversation = await prisma.conversations.create({
+			data: {
+				channel: "ai",
+				organisation_id: old.organisation_id,
+				user_id: old.user_id,
+				title: "New chat",
+				status: "active",
+				channel_data: {
+					assistant_type: cd.assistant_type,
+					source: "authed-chat",
+					total_input_tokens: 0,
+					total_output_tokens: 0,
+				},
+				...(old.members ?? undefined ? { members: old.members } : {}),
+			},
+		});
+
+		log.info("[chatSession.clear] archived + created fresh", {
+			oldId: input.conversationId,
+			newId: conversation.id,
+		});
+		return {
+			conversationId: conversation.id,
+			messages: [],
+			tokenTotals: { inputTokens: 0, outputTokens: 0 },
+		};
+	}),
+
+	// list — the user's threads for this agent in the supplied (membership-
+	// verified) org, most-recent first. Powers the conversation history list.
+	// Includes a short preview from the latest user message in each thread.
+	list: authed.input(listSchema).handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma;
+		const user = context.user as SessionUser;
+		const { agentId, organisationId: orgId } = input;
+		const aType = assistantType(agentId);
+
+		const conversations = await prisma.conversations.findMany({
+			where: {
+				channel: "ai",
+				organisation_id: orgId,
+				user_id: user.id,
+				channel_data: { path: ["assistant_type"], equals: aType },
+			},
+			orderBy: { last_message_at: "desc" },
+			select: {
+				id: true,
+				title: true,
+				status: true,
+				last_message_at: true,
+				created_at: true,
+			},
+		});
+
+		if (conversations.length === 0) return { conversations: [] };
+
+		// One grouped fetch for the latest user message per thread (preview),
+		// mapped in JS — avoids an N+1.
+		const ids = conversations.map((c: any) => c.id);
+		const lastMsgs = await prisma.messages.findMany({
+			where: { conversation_id: { in: ids }, role: "user" },
+			orderBy: { occurred_at: "desc" },
+			select: { conversation_id: true, content: true },
+		});
+		const previewById = new Map<string, string>();
+		for (const m of lastMsgs) {
+			if (!previewById.has(m.conversation_id)) {
+				previewById.set(
+					m.conversation_id,
+					(m.content ?? "").slice(0, 120),
+				);
+			}
+		}
+
+		return {
+			conversations: conversations.map((c: any) => ({
+				id: c.id,
+				title: c.title,
+				status: c.status,
+				last_message_at: c.last_message_at ?? c.created_at,
+				preview: previewById.get(c.id) ?? "",
+			})),
+		};
+	}),
+
+	// load — switch to a past thread from the history list. Returns its full
+	// message history (verbatim parts). Ownership is user_id (assertOwns).
+	load: authed.input(loadSchema).handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma;
+		const user = context.user as SessionUser;
+		const conv = await assertOwns(prisma, input.conversationId, user);
+
+		const msgs = await prisma.messages.findMany({
+			where: { conversation_id: input.conversationId },
+			orderBy: { occurred_at: "asc" },
+		});
+		const cd = (conv.channel_data ?? {}) as Record<string, unknown>;
+		return {
+			conversationId: conv.id,
+			messages: mapMessages(msgs),
+			tokenTotals: {
+				inputTokens: (cd.total_input_tokens as number) ?? 0,
+				outputTokens: (cd.total_output_tokens as number) ?? 0,
+			},
+		};
+	}),
+};

package/src/fn-routers/email-defaults.ts

@@ -0,0 +1,22 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Cached reader for the `email-defaults` config row's `default_sender` — the
+ * from-address for outbound transactional email (agreement/proposal/assessment
+ * senders). Replaces the former process.env.DEFAULT_EMAIL_SENDER read
+ * (configured-primitives: the registry row is the source of truth, not env).
+ */
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+const FALLBACK_SENDER = "noreply@gateway.scala.business";
+let cached: string | undefined;
+
+export async function getDefaultEmailSender(): Promise<string> {
+	if (cached !== undefined) return cached;
+	const row = await loadRegistryConfig("config", "email-defaults", v.looseObject({}));
+	cached = (row?.default_sender as string | undefined) ?? FALLBACK_SENDER;
+	return cached;
+}

package/src/fn-routers/email-link-ttl.ts

@@ -0,0 +1,23 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Cached reader for the `email-links` config row's `email_link_ttl_ms` — the
+ * validity window for agreement/proposal email-access magic links (dedup'd
+ * across the 3 fn-routers that mint them). Replaces the former per-file
+ * hardcoded EMAIL_LINK_TTL_MS constant (config-constants: the registry row is
+ * the source of truth, not the literal).
+ */
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+const DEFAULT_EMAIL_LINK_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+let cached: number | undefined;
+
+export async function getEmailLinkTtlMs(): Promise<number> {
+	if (cached !== undefined) return cached;
+	const row = await loadRegistryConfig("config", "email-links", v.looseObject({}));
+	cached = (row?.email_link_ttl_ms as number | undefined) ?? DEFAULT_EMAIL_LINK_TTL_MS;
+	return cached;
+}

package/src/fn-routers/index.ts

@@ -0,0 +1,70 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Composes auth, tasks, work-items, plans, chat-session, public-gpt-session,
+ * public-agreement, and user-preferences routers into the `fn` namespace and
+ * registers it via registerCustomRouter.
+ * Called at boot by registerFnRouters() — invoked before any ORPC dispatch.
+ *
+ * Also exposes the `regions` namespace on the client /api/rpc mount: a single
+ * `loadPage` procedure (reusing puckPagesRouter.loadFromWebsite) so a client
+ * RegionPageSwap can fetch a region's Puck page on demand and render it into a
+ * slot — the no-reload half of `region-views-are-pages` (every region is a Puck
+ * page; switching a view loads a different page's content). loadById is NOT
+ * exposed (website+path is the client-facing contract, not raw page ids).
+ */
+
+import { registerCustomRouter } from "@teamscala/orpc/app-router";
+import { puckPagesRouter } from "@teamscala/service-boot/page-server-orpc/puck-pages-router";
+import { watchDataChange } from "@teamscala/realtime-utils/data-change-procedure";
+import { watchPresence } from "@teamscala/realtime-utils/presence-procedure";
+import { aiHealthHandler } from "./ai-health-router.ts";
+import { resolvePanelDataHandler } from "./panel-data-router.ts";
+import { agreementSendRouter } from "./agreement-send-router.ts";
+import { cacheAdminRouter } from "./cache-admin-router.ts";
+import { chatSessionRouter } from "./chat-session-router.ts";
+import { proposalSendRouter } from "./proposal-send-router.ts";
+import { authRouter } from "./auth-router.ts";
+import { plansRouter } from "./plans-router.ts";
+import { publicAgreementRouter } from "./public-agreement-router.ts";
+import { publicAssessmentRouter } from "./public-assessment-router.ts";
+import { publicGptSessionRouter } from "./public-gpt-session-router.ts";
+import { signInFlowRouter } from "./sign-in-flow-router.ts";
+import { taskSyncRouter } from "./task-sync-router.ts";
+import { tasksRouter } from "./tasks-router.ts";
+import { userPreferencesRouter } from "./user-preferences-router.ts";
+import { userPreferencesRouter as portalPreferencesRouter } from "../page-server-orpc/user-preferences-router.ts";
+import { workItemsRouter } from "./work-items-router.ts";
+
+export function registerFnRouters(): void {
+	registerCustomRouter("fn", {
+		aiHealth: aiHealthHandler,
+		agreementSend: agreementSendRouter,
+		proposalSend: proposalSendRouter,
+		auth: authRouter,
+		cacheAdmin: cacheAdminRouter,
+		chatSession: chatSessionRouter,
+		publicAgreement: publicAgreementRouter,
+		publicAssessment: publicAssessmentRouter,
+		publicGptSession: publicGptSessionRouter,
+		signInFlow: signInFlowRouter,
+		tasks: tasksRouter,
+		taskSync: taskSyncRouter,
+		workItems: workItemsRouter,
+		userPreferences: userPreferencesRouter,
+		portalPreferences: portalPreferencesRouter,
+		plans: plansRouter,
+	});
+	registerCustomRouter("regions", {
+		loadPage: puckPagesRouter.loadFromWebsite,
+		// Resolve a page-kind panel's OWN loaderData (panel_view.loader_slug) so a
+		// panel region renders against the panel page's data, not the host's.
+		resolvePanelData: resolvePanelDataHandler,
+	});
+	registerCustomRouter("realtime", {
+		watchDataChange,
+		watchPresence,
+	});
+}

package/src/fn-routers/panel-data-router.ts

@@ -0,0 +1,93 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * `regions.resolvePanelData` — resolves a page-kind panel's OWN loaderData so a
+ * panel region renders blocks against the panel page's data, not the host
+ * page's. RegionPageSwap calls this on panel-open + injects the result via
+ * LiveDataProvider("page-data"), making panel-embedded data blocks (e.g. the
+ * workload Chart) self-sufficient: each panel carries its own data, no host
+ * coupling + no preloading the host route.
+ *
+ * Flow (registry reads via the loadRegistryConfig helper — registry-via-helper):
+ * panel_view.content.loader_slug → resource_loader config → orgId derived from
+ * the serving website (builda_websites.organisation_id) → resolveFromLoaderConfig
+ * → the loader's resolved sources. Panels without a loader_slug (e.g. the AI
+ * panel, whose block self-loads) return null — no extra round-trip, no behavior
+ * change.
+ */
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { resolveFromLoaderConfig } from "../resolve-from-loader-config.ts";
+
+interface Context {
+	prisma: {
+		builda_websites: {
+			findFirst: (args: unknown) => Promise<{
+				organisation_id?: string | null;
+			} | null>;
+		};
+	};
+}
+
+const panelViewSchema = v.looseObject({
+	content: v.looseObject({ loader_slug: v.optional(v.string()) }),
+});
+
+export const resolvePanelDataHandler = os
+	.$context<Context>()
+	.input(
+		v.object({
+			panelSlug: v.string(),
+			websiteSlug: v.string(),
+			/** Tenant orgId (preferred over the website's organisation_id, which is
+			 * the platform org on a multi-tenant portal — not the tenant). The
+			 * caller (RegionPageSwap) threads this from __PAGE_DATA__.orgId. */
+			orgId: v.optional(v.string()),
+		}),
+	)
+	.handler(async ({ input, context }) => {
+		// panel_view → loader_slug (null when missing or the panel has no loader).
+		let loaderSlug: string | undefined;
+		try {
+			const pv = await loadRegistryConfig(
+				"panel_view",
+				input.panelSlug,
+				panelViewSchema,
+			);
+			loaderSlug = pv.content?.loader_slug;
+		} catch {
+			return null;
+		}
+		if (!loaderSlug) return null;
+		// resource_loader → its config (loose schema; resolveFromLoaderConfig owns
+		// the typed LoaderConfig contract).
+		let loader: unknown;
+		try {
+			loader = await loadRegistryConfig(
+				"resource_loader",
+				loaderSlug,
+				v.unknown(),
+			);
+		} catch {
+			return null;
+		}
+		// Tenant orgId: prefer the caller-provided value (the route's tenant org,
+		// threaded from __PAGE_DATA__.orgId); fall back to the website's
+		// organisation_id (the platform org — wrong for multi-tenant portals, but
+		// the only derivable value when the caller omits it).
+		let orgId = input.orgId;
+		if (!orgId) {
+			const site = await context.prisma.builda_websites.findFirst({
+				where: { OR: [{ slug: input.websiteSlug }, { id: input.websiteSlug }] },
+				select: { organisation_id: true },
+			});
+			orgId = site?.organisation_id ?? undefined;
+		}
+		return await resolveFromLoaderConfig(
+			loader as Parameters<typeof resolveFromLoaderConfig>[0],
+			{ orgId },
+		);
+	});