@teamscala/service-boot 0.23.284

package/src/fn-routers/tasks-router.ts

@@ -0,0 +1,77 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for task creation with initial comment.
+ * Extracted from @teamscala/orpc/fn-router — primitives tier must not
+ * contain application-specific work_items logic.
+ */
+
+import { authed, type Context } from "./auth-router.ts";
+
+function toSession(ctx: Context): { userId: string; orgId: string | null } {
+	const user = ctx.user as { id: string; organisationId?: string | null };
+	return {
+		userId: user.id,
+		orgId: ctx.orgId || user.organisationId || null,
+	};
+}
+
+export const tasksRouter = {
+	createWithComment: authed.handler(async ({ input, context }) => {
+		const data = input as {
+			project_id: string;
+			title: string;
+			initial_comment: string;
+			status?: string;
+			assignee_id?: string;
+			due_date?: string;
+			start_date?: string;
+			time_estimate?: number;
+			assignee_type?: string;
+			agent_assignee_id?: string;
+			automation_type?: string;
+			responsible_party?: string;
+			depends_on?: string[];
+		};
+
+		if (!data.project_id) throw new Error("project_id is required");
+		if (!data.title) throw new Error("title is required");
+		if (!data.initial_comment) throw new Error("initial_comment is required");
+
+		const userId = toSession(context).userId;
+		const result = await (context.prisma as any).$transaction(
+			async (tx: any) => {
+				const task = await tx.work_items.create({
+					data: {
+						kind: "task",
+						project_id: data.project_id,
+						title: data.title,
+						status: data.status || "todo",
+						assignee_id: data.assignee_id || null,
+						due_date: data.due_date || null,
+						start_date: data.start_date || null,
+						time_estimate: data.time_estimate || null,
+						assignee_type: data.assignee_type || "user",
+						agent_assignee_id: data.agent_assignee_id || null,
+						automation_type: data.automation_type || "manual",
+						responsible_party: data.responsible_party || "team",
+						depends_on: data.depends_on || [],
+						created_by: userId,
+						updated_by: userId,
+					},
+				});
+				await tx.comments.create({
+					data: {
+						work_item_id: task.id,
+						content: data.initial_comment,
+						user_id: userId,
+					},
+				});
+				return task;
+			},
+		);
+		return { success: true, data: result };
+	}),
+};

package/src/fn-routers/user-preferences-router.ts

@@ -0,0 +1,139 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for a GENERIC per-user preference store backed by the
+ * `user_preferences` table. The user is resolved from the ORPC session context
+ * (`authed` middleware → `context.user.id`); the client supplies the org + key
+ * + value. This is the DB-durable, user-scoped key/value surface any feature
+ * can use — the AI browser-control focus (key `ai_ui_focus`) is the first
+ * consumer; it is NOT scala-projects-bespoke.
+ *
+ * Why this exists (over the generated `user_preferences` CRUD): the generated
+ * create/update do NOT resolve `user_id` server-side (only `organisation_id`
+ * from ctx.orgId), so a client cannot correctly write a per-user row through
+ * them. This proc stamps `user_id` from the authenticated caller, making the
+ * write safe + per-user. It also emits the `data_change` notify so the
+ * realtime surface (regions.watchDataChange) pushes updates to subscribed
+ * clients — the cross-region channel for the AI focus (the AiChat panel writes
+ * a focus here; the project-list-view in a different region subscribes +
+ * reacts, no shared React-context ancestor needed).
+ *
+ * Ownership is user_id: a caller reads/writes ONLY their own preferences. The
+ * org is part of the compound key (per-org isolation) but is client-supplied
+ * (the session carries the user, not the active org).
+ *
+ * DECISION — host-scoping of `user_preferences`: the table is NOT yet a shared
+ * `@teamscala/db` model (it lives in scala-projects's schema today), so this proc
+ * is genuinely host-scoped: it runs correctly on services whose Prisma client
+ * declares `user_preferences` (scala-projects is the first host) + is inert
+ * elsewhere. `Context.prisma` is `any`-typed, so the proc COMPILES workspace-
+ * wide (no type error on a model a host may not declare) — the `any` is the
+ * deliberate seam that lets one generic proc serve hosts incrementally as they
+ * adopt the table. Per-user preferences are platform-universal, so the tracked
+ * follow-on is to promote `user_preferences` to a shared `@teamscala/db` model
+ * (open-migration: `user_preferences→shared-model`, exit: every kind:ui host
+ * can mount this proc with no schema precondition) — at which point the proc is
+ * universally hostable + the `any` seam can tighten to the shared client. Until
+ * then the proc is opt-in per host (declare the table → get the capability).
+ */
+
+import * as v from "valibot";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { executeRawUnsafe } from "@teamscala/db/query-rows";
+import { authed, type Context } from "./auth-router.ts";
+
+interface SessionUser {
+	id: string;
+}
+
+const upsertSchema = v.object({
+	organisationId: v.string(),
+	/** The preference key (e.g. `ai_ui_focus`). Namespaced by feature. */
+	key: v.string(),
+	/** The JSON value. Arbitrary per feature — typed by the caller. */
+	value: v.any(),
+});
+
+const getSchema = v.object({
+	organisationId: v.string(),
+	key: v.string(),
+});
+
+/**
+ * Emit a best-effort `data_change` notify so realtime subscribers
+ * (regions.watchDataChange filtering on `user_preferences`) re-read + react.
+ * Mirrors the notify the generated CRUD emits. Never throws — realtime must
+ * never block a write (matches the generated create/update notify guard).
+ */
+async function notifyDataChange(
+	prisma: any,
+	organisationId: string,
+	op: string,
+): Promise<void> {
+	if (!organisationId) return;
+	try {
+		await (executeRawUnsafe as Function)(
+			"SELECT pg_notify('data_change', $1)",
+			JSON.stringify({ table: "user_preferences", op, org_id: organisationId }),
+		);
+	} catch {
+		/* best-effort */
+	}
+}
+
+export const userPreferencesRouter = {
+	// upsert — write (create-or-replace) the caller's preference value for
+	// (org, key). Stamps user_id from the session; the client never supplies it.
+	upsert: authed.input(upsertSchema).handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma;
+		const user = context.user as SessionUser;
+		const log = getAppLogger();
+		const { organisationId, key, value } = input;
+
+		try {
+			await prisma.user_preferences.upsert({
+				where: {
+					user_id_organisation_id_key: {
+						user_id: user.id,
+						organisation_id: organisationId,
+						key,
+					},
+				},
+				create: {
+					user_id: user.id,
+					organisation_id: organisationId,
+					key,
+					value,
+				},
+				update: { value },
+			});
+			await notifyDataChange(prisma, organisationId, "upsert");
+			return { success: true };
+		} catch (err) {
+			log.error(
+				`[userPreferences.upsert] failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			throw err;
+		}
+	}),
+
+	// get — read the caller's preference value for (org, key), or null. The
+	// initial read for a subscriber (the realtime notify then drives re-reads).
+	get: authed.input(getSchema).handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma;
+		const user = context.user as SessionUser;
+		const row = await prisma.user_preferences.findUnique({
+			where: {
+				user_id_organisation_id_key: {
+					user_id: user.id,
+					organisation_id: input.organisationId,
+					key: input.key,
+				},
+			},
+			select: { value: true, updated_at: true },
+		});
+		return { value: row?.value ?? null, updatedAt: row?.updated_at ?? null };
+	}),
+};

package/src/fn-routers/work-items-router.ts

@@ -0,0 +1,341 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedure for safely deleting a work_item (initiative/project/task).
+ * Refuses the delete when the row still has child rows (parent_id = id), so a
+ * delete can NEVER orphan its descendants — the tree must be emptied bottom-up.
+ *
+ * Initiatives, projects and tasks are all rows of the ONE `work_items` table
+ * discriminated by `kind`, and `parent_id` carries no DB-level foreign key, so
+ * a plain `work_items.delete` leaves dangling children with no referential
+ * integrity to stop it. This one guard covers every level (you may only delete
+ * a leaf — a node with no children), which is exactly the "empty it first"
+ * behaviour the board wants.
+ */
+
+import { createEmailClient } from "@teamscala/email-client/client";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { authed, type Context } from "./auth-router.ts";
+import { resolveAppBaseUrl } from "../resolve-app-base-url.ts";
+
+const emailClient = createEmailClient();
+
+export const workItemsRouter = {
+	/**
+	 * Fired client-side right after a task's status is set to
+	 * "pending_approval" (RaCI: the task's assignee is Responsible; the
+	 * project's Accountable person is the approver). Walks parent_id up to
+	 * the nearest project-kind ancestor, emails every accountable person on
+	 * it. Never throws to the caller — a notification failure must not block
+	 * the status change that already committed.
+	 */
+	requestApproval: authed.handler(async ({ input, context }) => {
+		const { id } = input as { id: string };
+		const log = getAppLogger();
+		const prisma = (context as Context).prisma as {
+			work_items: {
+				findUnique: (a: unknown) => Promise<{
+					id: string;
+					title: string;
+					kind: string;
+					parent_id: string | null;
+					organisation_id: string | null;
+				} | null>;
+			};
+			work_item_roles: {
+				findMany: (a: unknown) => Promise<{ user_id: string }[]>;
+			};
+			user: {
+				findUnique: (a: unknown) => Promise<{ id: string; email: string; name: string | null } | null>;
+			};
+			organisation_profile: {
+				findFirst: (a: unknown) => Promise<{ company_name: string | null } | null>;
+			};
+			notifications: {
+				create: (a: unknown) => Promise<unknown>;
+			};
+		};
+
+		try {
+			const task = await prisma.work_items.findUnique({
+				where: { id },
+				select: { id: true, title: true, kind: true, parent_id: true, organisation_id: true },
+			});
+			if (!task) return { notified: 0 };
+
+			let project = task;
+			while (project.kind !== "project" && project.parent_id) {
+				const parent = await prisma.work_items.findUnique({
+					where: { id: project.parent_id },
+					select: { id: true, title: true, kind: true, parent_id: true, organisation_id: true },
+				});
+				if (!parent) break;
+				project = parent;
+			}
+
+			const accountable = await prisma.work_item_roles.findMany({
+				where: { work_item_id: project.id, role: "accountable" },
+			});
+			if (accountable.length === 0) {
+				log.info("[work-items-router] requestApproval: no accountable person set", { taskId: id, projectId: project.id });
+				return { notified: 0 };
+			}
+
+			const requester = context.user as { id: string; name?: string | null; email?: string | null } | null;
+			const org = await prisma.organisation_profile.findFirst({
+				where: { id: task.organisation_id },
+				select: { company_name: true },
+			});
+			const linkUrl = `${await resolveAppBaseUrl()}/${task.organisation_id}?panel=task-comments&comment=${task.id}`;
+			const requesterName = requester?.name ?? requester?.email ?? "Someone";
+
+			let notified = 0;
+			for (const role of accountable) {
+				const user = await prisma.user.findUnique({ where: { id: role.user_id }, select: { id: true, email: true, name: true } });
+				if (!user?.email) continue;
+				const result = await emailClient.send({
+					to: user.email,
+					template: "task-awaiting-approval",
+					vars: {
+						recipient_name: user.name ?? user.email,
+						requester_name: requesterName,
+						project_title: project.title,
+						task_title: task.title,
+						task_url: linkUrl,
+						org_name: org?.company_name ?? "your organisation",
+					},
+				});
+				if (result.status !== "failed") notified++;
+				try {
+					await prisma.notifications.create({
+						data: {
+							organisation_id: task.organisation_id,
+							user_id: role.user_id,
+							type: "approval_request",
+							title: `${requesterName} requested approval`,
+							body: task.title,
+							work_item_id: task.id,
+							link_url: linkUrl,
+						},
+					});
+				} catch (err) {
+					log.error("[work-items-router] requestApproval: failed to write notification row", {
+						taskId: id,
+						userId: role.user_id,
+						error: err instanceof Error ? err.message : String(err),
+					});
+				}
+			}
+			return { notified };
+		} catch (err) {
+			log.error("[work-items-router] requestApproval failed", { taskId: id, error: err instanceof Error ? err.message : String(err) });
+			return { notified: 0 };
+		}
+	}),
+	/**
+	 * Fired client-side right after a comment is created, when the comment
+	 * text contains an @mention the client already resolved to a team-member
+	 * id (client does the name matching against the people list it already
+	 * has loaded; this handler only sends). Never throws to the caller for
+	 * same reason as requestApproval -- a notification failure must not
+	 * surface as a failed comment post.
+	 */
+	notifyMentions: authed.handler(async ({ input, context }) => {
+		const { workItemId, mentionedUserIds, commentExcerpt } = input as {
+			workItemId: string;
+			mentionedUserIds: string[];
+			commentExcerpt: string;
+		};
+		const log = getAppLogger();
+		const prisma = (context as Context).prisma as {
+			work_items: {
+				findUnique: (a: unknown) => Promise<{ id: string; title: string; organisation_id: string | null } | null>;
+			};
+			user: {
+				findUnique: (a: unknown) => Promise<{ id: string; email: string; name: string | null } | null>;
+			};
+			notifications: {
+				create: (a: unknown) => Promise<unknown>;
+			};
+		};
+		if (!mentionedUserIds || mentionedUserIds.length === 0) return { notified: 0 };
+		try {
+			const task = await prisma.work_items.findUnique({
+				where: { id: workItemId },
+				select: { id: true, title: true, organisation_id: true },
+			});
+			if (!task) return { notified: 0 };
+			const author = context.user as { id: string; name?: string | null; email?: string | null } | null;
+			const commentUrl = `${await resolveAppBaseUrl()}/${task.organisation_id}?panel=task-comments&comment=${task.id}`;
+			const authorName = author?.name ?? author?.email ?? "Someone";
+			const excerpt = commentExcerpt.slice(0, 280);
+
+			let notified = 0;
+			for (const userId of new Set(mentionedUserIds)) {
+				if (userId === author?.id) continue;
+				let user: { id: string; email: string; name: string | null } | null = null;
+				try {
+					user = await prisma.user.findUnique({ where: { id: userId }, select: { id: true, email: true, name: true } });
+				} catch (err) {
+					log.error("[work-items-router] notifyMentions: user lookup failed", { userId, error: err instanceof Error ? err.message : String(err) });
+					continue;
+				}
+				if (!user?.email) continue;
+				let result: { status: string };
+				try {
+					result = await emailClient.send({
+						to: user.email,
+						template: "comment-mention",
+						vars: {
+							recipient_name: user.name ?? user.email,
+							author_name: authorName,
+							task_title: task.title,
+							comment_excerpt: excerpt,
+							comment_url: commentUrl,
+						},
+					});
+				} catch (err) {
+					log.error("[work-items-router] notifyMentions: emailClient.send threw", { userId, error: err instanceof Error ? err.message : String(err) });
+					result = { status: "failed" };
+				}
+				if (result.status !== "failed") notified++;
+				try {
+					await prisma.notifications.create({
+						data: {
+							organisation_id: task.organisation_id,
+							user_id: userId,
+							type: "mention",
+							title: `${authorName} mentioned you`,
+							body: excerpt,
+							work_item_id: task.id,
+							link_url: commentUrl,
+						},
+					});
+				} catch (err) {
+					log.error("[work-items-router] notifyMentions: failed to write notification row", {
+						workItemId,
+						userId,
+						error: err instanceof Error ? err.message : String(err),
+					});
+				}
+			}
+			return { notified };
+		} catch (err) {
+			log.error("[work-items-router] notifyMentions failed", { workItemId, error: err instanceof Error ? err.message : String(err) });
+			return { notified: 0 };
+		}
+	}),
+	/**
+	 * Org-scoped member list for the task-comments panel — @mention matching AND
+	 * comment-sender display (name + avatar). ChatPanel.tsx has no
+	 * serverLoader/orgId prop (client-only overlay content), so it can't do the
+	 * SSR raw-SQL org-scope join load-project-list-view.ts uses; this exposes
+	 * the same result via a custom procedure instead of widening service_schema
+	 * to the raw better_auth_member table.
+	 *
+	 * This is the SINGLE source of member display info for the comments panel:
+	 * it coalesces BOTH name/email/avatar families on the user model into one
+	 * shape (the `full_name`/`primary_email`/`avatar_url` family AND the
+	 * better-auth `name`/`email`/`image` family). Returning avatar here lets the
+	 * client resolve sender name+avatar from this one list and drop the separate
+	 * `user.findMany` enrichment fetch it previously ran as a second waterfall
+	 * hop after `comments.findMany` (loading-shape: one wave-parallel hit, not a
+	 * dependent client-side round-trip chain).
+	 */
+	orgMembers: authed.handler(async ({ input, context }) => {
+		const { orgId } = input as { orgId: string };
+		const prisma = (context as Context).prisma as {
+			$queryRawUnsafe: <T>(sql: string, ...params: unknown[]) => Promise<T>;
+			user: {
+				findMany: (a: unknown) => Promise<{
+					id: string;
+					name: string | null;
+					email: string | null;
+					image: string | null;
+					full_name: string | null;
+					primary_email: string | null;
+					avatar_url: string | null;
+					avatar_thumb_url: string | null;
+				}[]>;
+			};
+		};
+		if (!orgId) return [];
+		const memberIds = (
+			await prisma.$queryRawUnsafe<{ user_id: string }[]>(
+				"SELECT user_id FROM better_auth_member WHERE organization_id = $1",
+				orgId,
+			)
+		).map((m) => m.user_id);
+		if (memberIds.length === 0) return [];
+		const users = await prisma.user.findMany({
+			where: { id: { in: memberIds } },
+			select: {
+				id: true,
+				name: true,
+				email: true,
+				image: true,
+				full_name: true,
+				primary_email: true,
+				avatar_url: true,
+				avatar_thumb_url: true,
+			},
+		});
+		return users.map((u) => ({
+			id: u.id,
+			name: u.full_name || u.name || "",
+			email: u.primary_email || u.email || "",
+			avatar: u.avatar_url || u.image || u.avatar_thumb_url || null,
+		}));
+	}),
+	deleteEmpty: authed.handler(async ({ input, context }) => {
+		const { id } = input as { id: string };
+		if (!id) throw new Error("id is required");
+		const prisma = (context as Context).prisma as {
+			work_items: {
+				findUnique: (a: unknown) => Promise<{
+					id: string;
+					kind: string;
+					organisation_id: string | null;
+				} | null>;
+				count: (a: unknown) => Promise<number>;
+				delete: (a: unknown) => Promise<unknown>;
+			};
+		};
+
+		const item = await prisma.work_items.findUnique({
+			where: { id },
+			select: { id: true, kind: true, organisation_id: true },
+		});
+		if (!item) throw new Error("Work item not found");
+
+		// Org-scope parity with the generated CRUD: a non-super-admin may only
+		// delete within their active organisation.
+		const user = context.user as { id: string; isSuperAdmin?: boolean } | null;
+		const orgId = (context as Context).orgId ?? null;
+		if (
+			!user?.isSuperAdmin &&
+			item.organisation_id &&
+			item.organisation_id !== orgId
+		) {
+			const { ORPCError } = await import("@orpc/server");
+			throw new ORPCError("FORBIDDEN", {
+				message: "You can only delete items in your own organisation.",
+			});
+		}
+
+		const childCount = await prisma.work_items.count({
+			where: { parent_id: id },
+		});
+		if (childCount > 0) {
+			const { ORPCError } = await import("@orpc/server");
+			throw new ORPCError("CONFLICT", {
+				message: `Can't delete this ${item.kind}: it still has ${childCount} item${childCount === 1 ? "" : "s"} inside it. Empty it first, then delete.`,
+			});
+		}
+
+		await prisma.work_items.delete({ where: { id } });
+		return { success: true };
+	}),
+};

package/src/gate-ttls.ts

@@ -0,0 +1,56 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Cached readers for the content-gate access-token TTL config rows
+ * (agreement-gate / proposal-gate / gpt-gate). initGateTtls() runs once at boot
+ * (two-phase-boot, before the gates mount) to populate the cache from the
+ * registry rows; the sync getters (agTtlMs/propTtlMs/gptTtlMs) return the
+ * cached value — or the former hardcoded default before init / on row-miss — so
+ * the sync AccessConfig.ttlMs fields + sync hono magic-link handlers read them
+ * without async. Replaces the per-file AG_TTL_MS / PROP_TTL_MS / GPT_TTL_MS
+ * constants (config-constants: the registry row is the source, dedup'd across
+ * each gate + its attach-* magic counterpart so token TTL and cookie maxAge
+ * never drift).
+ */
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+const DEFAULT_AG_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_PROP_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_GPT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+let _agTtlMs = DEFAULT_AG_TTL_MS;
+let _propTtlMs = DEFAULT_PROP_TTL_MS;
+let _gptTtlMs = DEFAULT_GPT_TTL_MS;
+let _initialized = false;
+
+/** Populate the TTL cache from the registry rows. Idempotent; keeps defaults on
+ *  any miss so the gates ALWAYS render (protective-layers-fail-explicitly). */
+export async function initGateTtls(): Promise<void> {
+	if (_initialized) return;
+	_initialized = true;
+	try {
+		const [ag, prop, gpt] = await Promise.all([
+			loadRegistryConfig("config", "agreement-gate", v.looseObject({})),
+			loadRegistryConfig("config", "proposal-gate", v.looseObject({})),
+			loadRegistryConfig("config", "gpt-gate", v.looseObject({})),
+		]);
+		if (typeof ag?.ag_ttl_ms === "number") _agTtlMs = ag.ag_ttl_ms;
+		if (typeof prop?.prop_ttl_ms === "number") _propTtlMs = prop.prop_ttl_ms;
+		if (typeof gpt?.gpt_ttl_ms === "number") _gptTtlMs = gpt.gpt_ttl_ms;
+	} catch {
+		// keep defaults
+	}
+}
+
+export function agTtlMs(): number {
+	return _agTtlMs;
+}
+export function propTtlMs(): number {
+	return _propTtlMs;
+}
+export function gptTtlMs(): number {
+	return _gptTtlMs;
+}

package/src/gpt-gate.ts

@@ -0,0 +1,76 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The PUBLIC GPT identity gate, expressed as config for the content-gate
+ * primitive (content-gate/). Unlike proposals/agreements this is NOT access
+ * control — every email is a valid visitor (lead capture). Its whole job is to
+ * make a returning visitor's identity known AT SSR so the GPT body renders the
+ * real conversation on first paint instead of server-rendering the capture gate
+ * and then swapping to the chat after hydration (the ssr-then-live-handoff +
+ * "know the visitor at SSR first paint" violation: building-applications).
+ *
+ * Flow: the capture form POSTs {gptId, email} to /api/gpt-access (openCapture →
+ * any email matches); the access endpoint sets a signed `gpt_token` cookie. On
+ * the next request runContentGate verifies that cookie for this agent and seeds
+ * resolved.initialVisitor — which the GPT body serverLoader (ssrGptSession) then
+ * uses to SSR-restore the conversation, and GptBodyBlock uses to skip the gate.
+ * onUnauthorized is a no-op: an un-gated (first-time) visitor sees the capture
+ * form the block renders itself when no visitor is known — that is correct, not
+ * a flash (they ARE anonymous), so there is nothing to withhold.
+ */
+
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+import { signAccessToken, verifyAccessTokenIdentity } from "./content-gate/token.ts";
+import { gptTtlMs } from "./gate-ttls.ts";
+
+const GPT_COOKIE = "gpt_token";
+// A GPT visitor returns over days/weeks; keep the identity cookie long-lived so
+// the conversation is restored on every revisit without re-entering the email.
+
+export const gptGateConfig: ContentGateConfig = {
+	cookieName: GPT_COOKIE,
+	getResourceId(resolved) {
+		// The GPT route resolves the agent into resolved.agent (the same entity
+		// the page title + GptBodyBlock derive from). No agent → not a GPT page →
+		// the engine no-ops.
+		const agent = resolved.agent as { id?: unknown } | null | undefined;
+		return typeof agent?.id === "string" ? agent.id : "";
+	},
+	verifyToken(token, resourceId, nowMs) {
+		return verifyAccessTokenIdentity(token, GPT_COOKIE, resourceId, nowMs);
+	},
+	onAuthorized(resolved, _resourceId, { email, name }) {
+		// Seed the verified visitor identity (building-applications initialVisitor)
+		// with the name carried in the token, so the header AND body render the
+		// full identity at SSR — and the body serverLoader (ssrGptSession) restores
+		// the conversation from the email. No client-side gate→chat swap.
+		(resolved as {
+			initialVisitor?: { name?: string; email: string };
+		}).initialVisitor = { name, email };
+	},
+	onUnauthorized() {
+		// No-op: a first-time/anonymous visitor correctly sees the capture form
+		// GptBodyBlock renders when no visitor is known. Nothing to withhold —
+		// the GPT page body is not gated content, only its identity is.
+	},
+};
+
+export const gptAccessConfig: AccessConfig = {
+	path: "/api/gpt-access",
+	cookieName: GPT_COOKIE,
+	get ttlMs() {
+		return gptTtlMs();
+	},
+	recordIdField: "gptId",
+	// Lead capture: any email is a valid visitor (no allow-list).
+	openCapture: true,
+	// Never called under openCapture; present to satisfy the config contract.
+	async resolveAuthorizedEmails() {
+		return new Set<string>();
+	},
+	signToken(resourceId, email, nowMs, name) {
+		return signAccessToken(GPT_COOKIE, resourceId, email, nowMs, gptTtlMs(), name);
+	},
+};