@teamscala/service-boot 0.23.284

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

@@ -0,0 +1,116 @@
+/**
+ * @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 { os } from "@orpc/server";
+import { TemplateSettingsPortalsConfigSchema } from "@teamscala/db-validation/registry-schemas/template-settings-portals";
+import { TemplateSettingsPublicConfigSchema } from "@teamscala/db-validation/registry-schemas/template-settings-public";
+import { getEntry } from "@teamscala/db/registry/accessors";
+import * as v from "valibot";
+
+const SCHEMA_BY_SLUG: Record<
+	string,
+	v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>
+> = {
+	"portals-template": TemplateSettingsPortalsConfigSchema,
+	"public-template": TemplateSettingsPublicConfigSchema,
+};
+
+const procedure = os;
+
+export const templatesRouter = {
+	getSettings: procedure
+		.input(v.object({ slug: v.string() }))
+		.handler(async ({ input }) => {
+			const schema = SCHEMA_BY_SLUG[input.slug];
+			if (!schema) {
+				throw new Error(
+					`templates.getSettings: unknown template slug "${input.slug}"`,
+				);
+			}
+			const entry = getEntry("template_settings" as never, input.slug);
+			if (!entry) {
+				throw new Error(
+					`templates.getSettings: row missing for slug "${input.slug}"`,
+				);
+			}
+			const config =
+				typeof entry.config === "string"
+					? JSON.parse(entry.config)
+					: entry.config;
+			return v.parse(schema, config);
+		}),
+
+	/**
+	 * 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: procedure
+		.input(
+			v.object({ slug: v.string(), patch: v.record(v.string(), v.unknown()) }),
+		)
+		.handler(async ({ input }) => {
+			const schema = SCHEMA_BY_SLUG[input.slug];
+			if (!schema) {
+				throw new Error(
+					`templates.updateSettings: unknown template slug "${input.slug}"`,
+				);
+			}
+			const entry = getEntry("template_settings" as never, input.slug);
+			if (!entry) {
+				throw new Error(
+					`templates.updateSettings: row missing for slug "${input.slug}"`,
+				);
+			}
+			const current =
+				typeof entry.config === "string"
+					? JSON.parse(entry.config)
+					: entry.config;
+			const merged = deepMerge(current as Record<string, unknown>, input.patch);
+			const validated = v.parse(schema, merged);
+			return validated;
+		}),
+};
+
+function deepMerge(
+	target: Record<string, unknown>,
+	patch: Record<string, unknown>,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = { ...target };
+	for (const [key, value] of Object.entries(patch)) {
+		if (
+			value &&
+			typeof value === "object" &&
+			!Array.isArray(value) &&
+			target[key] &&
+			typeof target[key] === "object" &&
+			!Array.isArray(target[key])
+		) {
+			out[key] = deepMerge(
+				target[key] as Record<string, unknown>,
+				value as Record<string, unknown>,
+			);
+		} else {
+			out[key] = value;
+		}
+	}
+	return out;
+}
+
+export type TemplatesRouter = typeof templatesRouter;

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

@@ -0,0 +1,132 @@
+/**
+ * @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 { os } from "@orpc/server";
+import type { PrismaClient } from "@teamscala/db/client";
+import * as v from "valibot";
+
+const procedure = os;
+
+// Typed portal UI preferences shape (the `portal` key inside user.preferences).
+// Owned here because the page-server is the sole reader/writer of this key, and
+// db-validation's generated user-preferences schema is a loose `v.record` that
+// can't express this typed all-optional ("partial") shape. Used for both the
+// mutation input and the merged-result re-validation below.
+const portalPreferencesPartialSchema = v.object({
+	// Per-user dark/light choice. Read server-side into the shell's initialTheme
+	// (so a refresh keeps the user's choice instead of resetting to the org brand
+	// default); written on the toolbar theme toggle.
+	theme: v.optional(v.nullable(v.picklist(["light", "dark"]))),
+	paneLeftWidth: v.optional(v.number()),
+	paneRightWidth: v.optional(v.number()),
+	sidebarCollapsed: v.optional(v.boolean()),
+	activePanel: v.optional(v.nullable(v.string())),
+	panelSizes: v.optional(
+		v.object({ main: v.optional(v.number()), right: v.optional(v.number()) }),
+	),
+	conversationId: v.optional(v.nullable(v.string())),
+	brandCache: v.optional(
+		v.nullable(
+			v.object({
+				logo: v.object({
+					light: v.optional(v.nullable(v.string())),
+					dark: v.optional(v.nullable(v.string())),
+					brand: v.optional(v.nullable(v.string())),
+				}),
+				primaryColor: v.optional(v.string()),
+			}),
+		),
+	),
+});
+
+type C = { prisma?: unknown; user?: { id?: string } | null };
+
+function getPrisma(c: unknown) {
+	const db = (c as C).prisma;
+	if (!db) throw new Error("userPreferences: context.prisma is required");
+	return db as PrismaClient;
+}
+
+export const userPreferencesRouter = {
+	/**
+	 * Read the current user's portal preferences from user.preferences.portal.
+	 * Returns null portal if no preferences exist yet.
+	 */
+	getPortalPreferences: procedure.handler(async ({ context }) => {
+		const prisma = getPrisma(context);
+		const userId = (context as C).user?.id;
+		if (!userId) return { portal: null };
+
+		const user = await prisma.user.findUnique({
+			where: { id: userId },
+			select: { preferences: true },
+		});
+
+		const prefs = (user?.preferences as Record<string, unknown> | null) ?? {};
+		const portal = (prefs.portal as Record<string, unknown> | undefined) ?? null;
+		if (!portal) return { portal: null };
+
+		return { portal };
+	}),
+
+	/**
+	 * 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: procedure
+		.input(v.object({ patch: portalPreferencesPartialSchema }))
+		.handler(async ({ context, input }) => {
+			const prisma = getPrisma(context);
+			const userId = (context as C).user?.id;
+			if (!userId) throw new Error("updatePortalPreferences: no user id in context");
+
+			const user = await prisma.user.findUnique({
+				where: { id: userId },
+				select: { preferences: true },
+			});
+
+			const current = ((user?.preferences as Record<string, unknown>) ?? {}) as Record<
+				string,
+				unknown
+			>;
+			const existingPortal = ((current.portal as Record<string, unknown>) ?? {}) as Record<
+				string,
+				unknown
+			>;
+
+			const mergedPortal = {
+				...existingPortal,
+				...input.patch,
+				panelSizes: input.patch.panelSizes
+					? { ...(existingPortal.panelSizes as Record<string, unknown>), ...input.patch.panelSizes }
+					: existingPortal.panelSizes,
+				brandCache:
+					input.patch.brandCache !== undefined
+						? input.patch.brandCache
+						: existingPortal.brandCache,
+			};
+
+			v.parse(portalPreferencesPartialSchema, mergedPortal);
+
+			await prisma.user.update({
+				where: { id: userId },
+				data: { preferences: JSON.parse(JSON.stringify({ ...current, portal: mergedPortal })) },
+			});
+
+			return { portal: mergedPortal };
+		}),
+};
+
+export type UserPreferencesRouter = typeof userPreferencesRouter;

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

@@ -0,0 +1,36 @@
+/**
+ * @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";
+import { createRegistry } from "@teamscala/generic-registry/create-registry";
+
+export type PgBossJobHandler = (ctx: {
+	config: ScheduledJobConfig;
+}) => Promise<void> | void;
+
+export const pgBossHandlerRegistry = createRegistry<PgBossJobHandler>(
+	"pg-boss-handlers",
+);
+
+/**
+ * Register a handler for a `scheduled_job.handler_slug`. Idempotent on re-import
+ * (createRegistry.register overwrites silently — last registration wins).
+ */
+export function registerScheduledJobHandler(
+	slug: string,
+	handler: PgBossJobHandler,
+): void {
+	pgBossHandlerRegistry.register(slug, handler);
+}

package/src/pg-boss-mount.ts

@@ -0,0 +1,295 @@
+/**
+ * @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 type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+import { validateRow } from "@teamscala/db-validation/validate-row";
+import { pgSslCompatUrl } from "@teamscala/db/provider/pg-ssl-compat";
+import { getAllEntries } from "@teamscala/db/registry/accessors";
+import type { RegistryEntry } from "@teamscala/db/registry/types";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { ScheduleOptions } from "pg-boss";
+import { PgBoss } from "pg-boss";
+import { pgBossHandlerRegistry } from "./pg-boss-handler-registry.ts";
+
+// Bundled pg-boss handlers self-register on import (package-subscriber shape).
+// External handler packages register via their own boot hook / subscriber import.
+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[];
+}
+
+function belongsToService(
+	entry: RegistryEntry,
+	serviceSlug: string,
+	packages: string[],
+): boolean {
+	const config = entry.config as Record<string, unknown>;
+	const handlerSlug = config.handler_slug as string | undefined;
+	if (!handlerSlug) return false;
+	// Explicit row-driven targeting takes precedence — a universal boot-package
+	// handler (e.g. one in @teamscala/service-boot, which no service declares in
+	// server_packages) cannot be scoped by the server_package prefix match.
+	const targetService = config.service_slug as string | undefined;
+	if (targetService) return targetService === serviceSlug;
+	return packages.some(
+		(pkg) => handlerSlug.startsWith(`${pkg}:`) || handlerSlug === pkg,
+	);
+}
+
+export function intervalToCron(intervalSeconds: number): string {
+	if (intervalSeconds < 60) {
+		return `*/${intervalSeconds} * * * * *`;
+	}
+	const minutes = Math.floor(intervalSeconds / 60);
+	if (minutes < 60) {
+		return `*/${minutes} * * * *`;
+	}
+	const hours = Math.floor(minutes / 60);
+	return `0 */${hours} * * *`;
+}
+
+async function resolveHandler(
+	handlerSlug: string,
+	config: ScheduledJobConfig,
+): Promise<void> {
+	const handler = pgBossHandlerRegistry.get(handlerSlug);
+	if (!handler) {
+		throw new Error(
+			`pg-boss handler "${handlerSlug}" has no registered function — ` +
+				`register it via pgBossHandlerRegistry.register(slug, fn) before the job fires`,
+		);
+	}
+	await handler({ config });
+}
+
+export async function mountPgBoss(
+	ctx: PgBossMountContext,
+): Promise<PgBossMountResult> {
+	const allEntries = getAllEntries();
+	const scheduledEntries = allEntries.filter(
+		(e) =>
+			(e.type as string) === "scheduled_job" &&
+			belongsToService(e, ctx.serviceSlug, ctx.packages),
+	);
+
+	if (scheduledEntries.length === 0) {
+		return { boss: null, jobs: [] };
+	}
+
+	const log = getAppLogger();
+	const jobs: MountedJob[] = [];
+
+	// pg-boss connects through pg, whose sslmode dialect differs from the
+	// shared URL's libpq spelling — route through the canonical rewrite.
+	// Config object (not a bare connectionString) so the internal pool is
+	// bounded + tagged for the ~220ms cross-internet dev→Railway RTT.
+	const boss = new PgBoss({
+		connectionString: pgSslCompatUrl(ctx.databaseUrl),
+		application_name: `pgboss:${ctx.serviceSlug}`,
+		// Same per-service budget as the application Prisma pool (railway.ts):
+		// ~30 consumers share one 200-conn Postgres; 3 keeps the aggregate ≤90.
+		max: 3,
+		// Generous connection-acquisition budget for the cross-internet link so
+		// a slow TLS handshake under sustained load doesn't terminate the conn.
+		connectionTimeoutMillis: 30_000,
+	});
+	// crash-isolation: pg-boss's manager emits 'error' on a worker-connection
+	// failure (a proxy-killed idle conn under sustained cross-internet writes).
+	// With NO listener, EventEmitter THROWS on emit('error'), the worker's
+	// promise rejects unhandled, and Bun exits the process — the scala-extract
+	// restart-storm of 2026-07-19. The listener makes it a logged, recovered
+	// event. This is the pg-boss-owned connection, the sibling of @teamscala/db's
+	// application-pool pool.on('error') handler (the app pool alone did not
+	// cover pg-boss's separate pool). Registered before start() so a boot-time
+	// error is caught too.
+	boss.on("error", (err) => {
+		log.warn(`[pg-boss:${ctx.serviceSlug}] recovered error event (process kept alive)`, {
+			error: err instanceof Error ? err.message : String(err),
+		});
+	});
+	boss.on("warning", (w) => {
+		log.warn(`[pg-boss:${ctx.serviceSlug}] warning`, { warning: String(w) });
+	});
+	// start() MUST precede work()/schedule() — it opens the DB connection;
+	// calling schedule() before start() crashes the timekeeper with
+	// "Database not opened. Call open() before executing SQL." (pg-boss v12)
+	await boss.start();
+
+	for (const entry of scheduledEntries) {
+		// crash-isolation: a malformed scheduled_job row degrades to "this job
+		// unavailable" (logged + event-log row), NEVER a boot-crash. A bare
+		// pg-boss assert reaching boot is the violation.
+		let config: ScheduledJobConfig;
+		try {
+			config = validateRow("scheduled_job", entry.config) as never as ScheduledJobConfig;
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			log.error(
+				`[pg-boss-mount:${ctx.serviceSlug}] scheduled_job "${entry.slug}" failed schema validation — skipping`,
+				{ reason },
+			);
+			recordEvent({
+				kind: "pgboss.job.skipped",
+				payload: { service: ctx.serviceSlug, slug: entry.slug, reason: `schema-invalid: ${reason}` },
+			});
+			continue;
+		}
+		if (!config.queue_name || !config.handler_slug) {
+			log.error(
+				`[pg-boss-mount:${ctx.serviceSlug}] scheduled_job "${entry.slug}" missing queue_name or handler_slug — skipping`,
+				{ queue_name: config.queue_name, handler_slug: config.handler_slug },
+			);
+			recordEvent({
+				kind: "pgboss.job.skipped",
+				payload: { service: ctx.serviceSlug, slug: entry.slug, reason: "missing queue_name or handler_slug" },
+			});
+			continue;
+		}
+		const queueName = config.queue_name;
+
+		try {
+			// pg-boss v12 requires the queue to exist before work()/schedule()
+			// dispatch against it ("Queue X does not exist") — createQueue's
+			// underlying SQL is ON CONFLICT DO NOTHING, so calling it on every
+			// boot is a safe idempotent assert, never a duplicate-creation error.
+			await boss.createQueue(queueName);
+			await boss.work(queueName, async () => {
+				await resolveHandler(config.handler_slug, config);
+			});
+
+			if (config.cron) {
+				const scheduleOpts: ScheduleOptions = {};
+				if (config.retry) {
+					scheduleOpts.retryLimit = config.retry.max_attempts;
+					scheduleOpts.retryDelay = config.retry.backoff_seconds;
+					scheduleOpts.retryBackoff = true;
+				}
+				await boss.schedule(queueName, config.cron, null, scheduleOpts);
+				jobs.push({
+					queueName,
+					handlerSlug: config.handler_slug,
+					cron: config.cron,
+				});
+			} else if (config.interval_seconds) {
+				const cron = intervalToCron(config.interval_seconds);
+				const scheduleOpts: ScheduleOptions = {};
+				if (config.retry) {
+					scheduleOpts.retryLimit = config.retry.max_attempts;
+					scheduleOpts.retryDelay = config.retry.backoff_seconds;
+					scheduleOpts.retryBackoff = true;
+				}
+				await boss.schedule(queueName, cron, null, scheduleOpts);
+				jobs.push({
+					queueName,
+					handlerSlug: config.handler_slug,
+					intervalSeconds: config.interval_seconds,
+				});
+			} else {
+				jobs.push({
+					queueName,
+					handlerSlug: config.handler_slug,
+				});
+			}
+		} catch (err) {
+			// crash-isolation for the mount path: a work()/schedule() failure
+			// (e.g. DB not open, queue conflict) degrades to "this job unavailable"
+			// (logged + event-log row), NEVER a boot-crash. Same treatment as the
+			// row-validation guard above.
+			const reason = err instanceof Error ? err.message : String(err);
+			log.error(
+				`[pg-boss-mount:${ctx.serviceSlug}] scheduled_job "${entry.slug}" failed to mount (work/schedule) — skipping`,
+				{ reason },
+			);
+			recordEvent({
+				kind: "pgboss.job.skipped",
+				payload: { service: ctx.serviceSlug, slug: entry.slug, reason: `mount-failed: ${reason}` },
+			});
+			continue;
+		}
+	}
+
+	// Reconcile orphaned cron schedules: unschedule any pg-boss schedule that no
+	// longer corresponds to an ACTIVE registry row. Deactivating/deleting a
+	// scheduled_job (or sync_job_handler) previously left its cron lingering in
+	// pgboss.schedule, firing indefinitely — 2 stale web-extractor schedules
+	// found 2026-07-27, still scraping every 3/15min months after the job was meant
+	// to be one-off. Deactivation must actually stop the cron. A schedule is
+	// "backed" iff ANY active registry row's slug OR queue_name equals its name —
+	// this covers scheduled_job AND sync_job_handler (and any future
+	// schedule-owning type) without hardcoding the type list, so live sync jobs
+	// (zoho_assist_sync, trackabi, …) are never touched. Runs on every pg-boss
+	// mount and reconciles GLOBALLY: an orphan is removed regardless of which
+	// service created it, since a cron with no active backing row is drift by
+	// definition. A service with zero active scheduled jobs early-returns above
+	// and never reaches here — scala-loga (7 cron jobs) is the reliable
+	// reconciler, but any service-with-jobs that boots cleans the full set.
+	try {
+		const backedScheduleNames = new Set(
+			allEntries.flatMap((e) => {
+				const cfg = e.config as { queue_name?: string } | null;
+				return [e.slug, cfg?.queue_name].filter(
+					(n): n is string => typeof n === "string" && n.length > 0,
+				);
+			}),
+		);
+		const liveSchedules = await boss.getSchedules();
+		for (const sched of liveSchedules) {
+			if (backedScheduleNames.has(sched.name)) continue;
+			log.warn(
+				`[pg-boss:${ctx.serviceSlug}] unscheduling orphaned cron "${sched.name}" (no active registry row backs it — drift)`,
+			);
+			await boss.unschedule(sched.name);
+			recordEvent({
+				kind: "pgboss.schedule.unscheduled",
+				payload: {
+					service: ctx.serviceSlug,
+					name: sched.name,
+					reason: "orphaned-no-active-backing-row",
+				},
+			});
+		}
+	} catch (err) {
+		// crash-isolation: a reconciliation failure degrades to "orphans not
+		// cleaned this boot" (logged), never a boot-crash — reconciled on the
+		// next successful mount.
+		log.warn(`[pg-boss:${ctx.serviceSlug}] schedule reconciliation failed`, {
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+
+	return { boss, jobs };
+}

package/src/proposal-authorized-emails.ts

@@ -0,0 +1,65 @@
+/**
+ * @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).
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { queryRows } from "@teamscala/db/query-rows";
+
+export async function resolveProposalAuthorizedEmails(
+	proposalId: string,
+): Promise<Set<string>> {
+	try {
+		const { getPrisma } = await import("@teamscala/db/prisma-registry");
+		const prisma = getPrisma();
+		const rows = await queryRows`
+			SELECT lower(u.email) AS email
+			  FROM better_auth_member m
+			  JOIN "user" u ON u.id = m.user_id
+			 WHERE m.organization_id = (
+			       SELECT organisation_id FROM proposals WHERE id = ${proposalId})
+			   AND u.email IS NOT NULL
+			UNION
+			SELECT lower(cd.primary_email) AS email
+			  FROM client_database cd
+			 WHERE cd.id = (SELECT contact_id FROM proposals WHERE id = ${proposalId})
+			   AND cd.primary_email IS NOT NULL
+			UNION
+			SELECT lower(cd.primary_email) AS email
+			  FROM client_database cd
+			 WHERE cd.company_id = (SELECT partner_id FROM proposals WHERE id = ${proposalId})
+			   AND cd.primary_email IS NOT NULL
+		` as { email: string }[];
+		return new Set(
+			rows.map((r) => (r.email ?? "").trim().toLowerCase()).filter(Boolean),
+		);
+	} catch (err) {
+		getAppLogger().error(
+			`[proposal-access] authorized-email resolve failed for ${proposalId}: ${err instanceof Error ? `${err.message} | ${err.stack}` : String(err)}`,
+		);
+		return new Set();
+	}
+}