@teamscala/service-boot 0.23.516 → 0.23.518

package/src/handlers/platform-fault-escalation.ts

@@ -1,246 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `platform-fault-escalation` pg-boss handler. Full contract in curated
- * `apps/escalation.md` — episodes EMIT ON TRANSITIONS ONLY; evidence bounded
- * `occurred_at <= now()` and cited by resolvable event id; delivery verified
- * by WhatsApp message id before `escalated_at` is recorded.
- *
- * This module is the SWEEP unit (load config → aggregate → decide → deliver/
- * resolve per kind, isolated). The machinery lives as siblings under
- * ./platform-fault-escalation/ (config, event-log-queries, orpc-client,
- * delivery) — split when the parent held them all at 500 lines; the pure
- * decision logic was already platform-fault-escalation-logic.ts.
- */
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import { recordEvent } from "@teamscala/event-log/record-event";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-import {
-	decideSweep,
-	episodeNeedsRefresh,
-	type EscalationEpisode,
-	type KindThresholdOverride,
-	type ZeroVolumeInputs,
-} from "./platform-fault-escalation-logic.ts";
-import { loadFaultEscalationConfig } from "./platform-fault-escalation/config.ts";
-import { probeHttpOk } from "./platform-fault-escalation/probe.ts";
-import { resolveHoldRaisedSince } from "./platform-fault-escalation/event-log-queries.ts";
-import {
-	fetchAggregates,
-	fetchVolumeCount,
-	zeroVolumeFlagActive,
-} from "./platform-fault-escalation/event-log-queries.ts";
-import { orpc } from "./platform-fault-escalation/orpc-client.ts";
-import {
-	clearZeroVolumeHold,
-	deliverEscalation,
-	deliverZeroVolumeHold,
-	refreshOpenEpisode,
-	rearmEpisode,
-	resolveEpisode,
-} from "./platform-fault-escalation/delivery.ts";
-
-async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig }): Promise<void> {
-	const log = getAppLogger();
-	const config = await loadFaultEscalationConfig();
-	const now = new Date();
-
-	const aggregates = await fetchAggregates(config.watched_kind_patterns, config.window_minutes);
-	// Only OPEN episodes matter: a resolved episode and no episode at all have
-	// the same meaning to decideSweep (a recurring sustained fault opens a NEW
-	// episode and escalates again).
-	const openEpisodes = (await (await orpc()).platform_fault_escalations.findMany({
-		where: { resolved_at: null },
-	})) as Array<{
-		kind: string;
-		first_seen_at: string | Date;
-		last_seen_at: string | Date;
-		event_count: number;
-		escalated_at: string | Date | null;
-		work_item_id: string | null;
-		resolved_at: string | Date | null;
-		rearmed_at: string | Date | null;
-		last_updated_at: string | Date | null;
-	}>;
-	const episodes: EscalationEpisode[] = openEpisodes.map((row) => ({
-		kind: row.kind,
-		firstSeenAt: new Date(row.first_seen_at),
-		lastSeenAt: new Date(row.last_seen_at),
-		eventCount: row.event_count,
-		escalatedAt: row.escalated_at ? new Date(row.escalated_at) : null,
-		workItemId: row.work_item_id,
-		resolvedAt: row.resolved_at ? new Date(row.resolved_at) : null,
-		rearmedAt: row.rearmed_at ? new Date(row.rearmed_at) : null,
-		lastUpdatedAt: row.last_updated_at ? new Date(row.last_updated_at) : null,
-	}));
-
-	const probeSources = config.probe_sources ?? {};
-	const kindThresholds: Record<string, KindThresholdOverride> = {};
-	for (const [kind, override] of Object.entries(config.kind_thresholds ?? {})) {
-		kindThresholds[kind] = {
-			minCount: override?.min_count,
-			minSpanMinutes: override?.min_span_minutes,
-		};
-	}
-
-	// ZERO-VOLUME INPUTS: per configured kind, resolve its source's window
-	// volume and standing-flag state so decideSweep can tell quiet apart
-	// from dead-producer. Computed here, pure decision stays in logic.
-	const volumeSources = config.volume_sources ?? {};
-	const zeroVolume: ZeroVolumeInputs = { sources: volumeSources, countByKind: {}, flagActiveByKind: {} };
-	for (const [kind, source] of Object.entries(volumeSources)) {
-		try {
-			zeroVolume.countByKind[kind] = await fetchVolumeCount(source.volume_kind_pattern, config.window_minutes);
-		} catch (err) {
-			log.error(
-				`[platform-fault-escalation] volume count for '${kind}' (~${source.volume_kind_pattern}) failed (${err instanceof Error ? err.message : String(err)}) — treating as unmeasured for this sweep`,
-			);
-		}
-	}
-
-	const decision = decideSweep(
-		aggregates,
-		episodes,
-		{
-			minCount: config.min_count,
-			minSpanMinutes: config.min_span_minutes,
-			resolveAfterMinutes: config.resolve_after_minutes,
-		},
-		now,
-		kindThresholds,
-		Object.keys(volumeSources).length > 0 ? zeroVolume : undefined,
-		probeSources,
-	);
-
-	// Per-kind isolation: one fault's delivery failure must never block the
-	// others. Failures are logged + emitted so the escalator itself is
-	// observable (the sweep that silently stops sweeping is the original bug).
-	for (const { aggregate } of decision.escalate) {
-		try {
-			const delivered = await deliverEscalation(aggregate.kind, aggregate, config);
-			log.warn(
-				`[platform-fault-escalation] ESCALATED '${aggregate.kind}' — ${delivered.messageId ? `WhatsApp message ${delivered.messageId}` : "work item only (agent-handled kind, operator not paged)"}, work item ${delivered.workItemId}`,
-			);
-		} catch (err) {
-			const reason = err instanceof Error ? err.message : String(err);
-			log.error(`[platform-fault-escalation] delivery for '${aggregate.kind}' failed (claim retained, retried next sweep): ${reason}`);
-			recordEvent({ kind: "platform.fault.escalation_failed", payload: { event_kind: aggregate.kind, reason } });
-		}
-	}
-	// AN OPEN EPISODE KEEPS ITS FACTS CURRENT. Escalation is a TRANSITION and
-	// fires once (`emit-transitions-not-conditions`) — but the ROW is the
-	// durable record of the condition, and a record that stops updating starts
-	// lying. Refreshing is not emitting: nothing is delivered here, no comment
-	// is written, no message is sent. Only the stored window facts move.
-	const aggregateByKind = new Map(aggregates.map((aggregate) => [aggregate.kind, aggregate]));
-	for (const episode of episodes) {
-		const aggregate = aggregateByKind.get(episode.kind);
-		if (!episodeNeedsRefresh(episode, aggregate) || !aggregate) continue;
-		try {
-			await refreshOpenEpisode(episode.kind, aggregate);
-		} catch (err) {
-			log.error(
-				`[platform-fault-escalation] refresh for '${episode.kind}' failed (facts stay stale for this sweep, retried next): ${err instanceof Error ? err.message : String(err)}`,
-			);
-		}
-	}
-
-	for (const { episode, quietMinutes } of decision.zeroVolumeHold) {
-		const source = volumeSources[episode.kind];
-		if (!source) continue;
-		try {
-			if (await zeroVolumeFlagActive(episode.kind)) continue; // hold already raised once
-			await deliverZeroVolumeHold(
-				episode,
-				quietMinutes,
-				zeroVolume.countByKind[episode.kind] ?? 0,
-				source,
-			);
-			log.warn(
-				`[platform-fault-escalation] ZERO-VOLUME HOLD raised for '${episode.kind}' — failures quiet AND producer quiet; episode held open`,
-			);
-		} catch (err) {
-			log.error(`[platform-fault-escalation] zero-volume hold for '${episode.kind}' failed (retried next sweep): ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
-	// PROBE-GATED RESOLUTION (operator ruling 2026-08-28): the recovery
-	// transition fires only when the subject's capability probe answers OK.
-	// An unreachable probe HOLDS the episode open — the close-refusal is
-	// raised ONCE per episode state as a durable event, never an alarm: the
-	// original verdict (failures went quiet) was correct; it lacked the
-	// probe behind the verdict.
-	let resolveProbeHeld = 0;
-	for (const { episode, quietMinutes, clearZeroVolumeFlag, probeUrl, probeTimeoutSeconds } of decision.resolveProbeGate) {
-		try {
-			if (await probeHttpOk(probeUrl, probeTimeoutSeconds)) {
-				await resolveEpisode(episode, quietMinutes);
-				if (clearZeroVolumeFlag) await clearZeroVolumeHold(episode, zeroVolume.countByKind[episode.kind] ?? 0);
-				log.info(`[platform-fault-escalation] RESOLVED '${episode.kind}' — capability probe ${probeUrl} answered OK after ${quietMinutes} quiet min`);
-			} else {
-				resolveProbeHeld += 1;
-				if (await resolveHoldRaisedSince(episode.kind, episode.lastUpdatedAt ?? episode.firstSeenAt)) continue;
-				recordEvent({
-					kind: "platform.fault.resolve_held",
-					payload: {
-						event_kind: episode.kind,
-						probe: probeUrl,
-						quiet_minutes: quietMinutes,
-						work_item_id: episode.workItemId,
-					},
-				});
-				log.warn(
-					`[platform-fault-escalation] resolve HELD for '${episode.kind}' — capability probe ${probeUrl} did not answer OK; episode stays open (raised once, not an alarm)`,
-				);
-			}
-		} catch (err) {
-			log.error(`[platform-fault-escalation] probe-gated resolve for '${episode.kind}' failed (episode stays open; retried next sweep): ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
-	for (const { episode, quietMinutes, clearZeroVolumeFlag } of decision.resolve) {
-		try {
-			await resolveEpisode(episode, quietMinutes);
-			if (clearZeroVolumeFlag) await clearZeroVolumeHold(episode, zeroVolume.countByKind[episode.kind] ?? 0);
-		} catch (err) {
-			log.error(`[platform-fault-escalation] resolve for '${episode.kind}' failed: ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
-	// RE-ARM, NOT RESOLVE (2026-08-29). A kind with no declared capability
-	// probe went quiet: the alarm is armed for the next occurrence and NOTHING
-	// is claimed about the condition. No operator comment is written here on
-	// purpose — see rearmEpisode.
-	for (const { episode, quietMinutes, clearZeroVolumeFlag } of decision.rearm) {
-		try {
-			await rearmEpisode(episode, quietMinutes);
-			if (clearZeroVolumeFlag) await clearZeroVolumeHold(episode, zeroVolume.countByKind[episode.kind] ?? 0);
-			log.info(`[platform-fault-escalation] RE-ARMED '${episode.kind}' after ${Math.round(quietMinutes)} quiet min — no probe declared, so the condition is UNVERIFIED and no close was claimed`);
-		} catch (err) {
-			log.error(`[platform-fault-escalation] re-arm for '${episode.kind}' failed (retried next sweep): ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
-
-	// Emitted every run, even when nothing fired — a sweep that only reports
-	// when it escalated is indistinguishable from one that stopped running.
-	recordEvent({
-		kind: "platform.fault.swept",
-		payload: {
-			watched_kinds: aggregates.length,
-			escalated: decision.escalate.length,
-			resolved: decision.resolve.length + (decision.resolveProbeGate.length - resolveProbeHeld),
-			resolve_probe_held: resolveProbeHeld,
-			zero_volume_holds: decision.zeroVolumeHold.length,
-		},
-	});
-	if (decision.escalate.length > 0 || decision.resolve.length > 0 || decision.zeroVolumeHold.length > 0) {
-		log.info(
-			`[platform-fault-escalation] sweep — ${aggregates.length} kind(s) watched, ${decision.escalate.length} escalated, ${decision.resolve.length} resolved`,
-		);
-	}
-	}
-
-	pgBossHandlerRegistry.register(
-	"@teamscala/service-boot:platform-fault-escalation",
-	platformFaultEscalationSweep as (ctx: { config: ScheduledJobConfig }) => Promise<void>,
-);

package/src/handlers/projects-digest.ts

@@ -1,198 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `projects-daily-digest` / `projects-weekly-digest` pg-boss handlers for
- * scala-projects. Fixed-query shape: no row-driven
- * SQL, every query is a literal Prisma call against work_items; the
- * scheduled_job row only carries the cron.
- *
- * Daily digest: per assignee, tasks assigned to them created in the last 24h.
- * Weekly digest: per assignee, their overdue tasks + tasks due in the next 7
- * days. Both group work_items by assignee_id so one org-wide query covers
- * every member, then send one email per assignee via the
- * projects-daily-digest / projects-weekly-digest email_template rows.
- *
- * Registered under `@teamscala/service-boot:projects-daily-digest` and
- * `@teamscala/service-boot:projects-weekly-digest`.
- */
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import { escapeHtml } from "@teamscala/formatters/escapeHtml";
-import { getPrisma } from "@teamscala/db/prisma-registry";
-import { createEmailClient } from "@teamscala/email-client/client";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-import { resolveAppBaseUrl } from "../resolve-app-base-url.ts";
-
-const emailClient = createEmailClient();
-
-interface DigestTask {
-	id: string;
-	title: string;
-	organisation_id: string;
-	assignee_id: string | null;
-}
-
-type PrismaClient = ReturnType<typeof getPrisma>;
-
-function taskLink(appUrl: string, task: DigestTask): string {
-	return `${appUrl}/${task.organisation_id}?panel=task-comments&comment=${task.id}`;
-}
-
-function renderListHtml(tasks: DigestTask[], appUrl: string): string {
-	if (tasks.length === 0) return "<p><em>None</em></p>";
-	const items = tasks.map((t) => `<li><a href="${taskLink(appUrl, t)}">${escapeHtml(t.title)}</a></li>`).join("");
-	return `<ul>${items}</ul>`;
-}
-
-function renderListText(tasks: DigestTask[]): string {
-	if (tasks.length === 0) return "None";
-	return tasks.map((t) => `- ${t.title}`).join("\n");
-}
-
-function groupByAssignee(tasks: DigestTask[]): Map<string, DigestTask[]> {
-	const map = new Map<string, DigestTask[]>();
-	for (const t of tasks) {
-		if (!t.assignee_id) continue;
-		const list = map.get(t.assignee_id) ?? [];
-		list.push(t);
-		map.set(t.assignee_id, list);
-	}
-	return map;
-}
-
-async function loadOrgNames(prisma: PrismaClient, orgIds: string[]): Promise<Map<string, string>> {
-	if (orgIds.length === 0) return new Map();
-	const rows = await prisma.organisation_profile.findMany({
-		where: { id: { in: orgIds } },
-		select: { id: true, company_name: true },
-	});
-	return new Map(rows.map((r: { id: string; company_name: string | null }) => [r.id, r.company_name || "your organisation"]));
-}
-
-async function loadUsers(
-	prisma: PrismaClient,
-	userIds: string[],
-): Promise<Map<string, { email: string; name: string }>> {
-	if (userIds.length === 0) return new Map();
-	const rows = await prisma.user.findMany({
-		where: { id: { in: userIds } },
-		select: { id: true, email: true, name: true },
-	});
-	return new Map(rows.map((r: { id: string; email: string; name: string }) => [r.id, { email: r.email, name: r.name }]));
-}
-
-export async function sendDailyDigest(_ctx: { config: ScheduledJobConfig }): Promise<void> {
-	const log = getAppLogger();
-	const prisma = getPrisma();
-	const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
-	const tasks = (await prisma.work_items.findMany({
-		where: { kind: "task", created_at: { gte: since }, assignee_id: { not: null } },
-		select: { id: true, title: true, organisation_id: true, assignee_id: true },
-	})) as DigestTask[];
-
-	const byAssignee = groupByAssignee(tasks);
-	if (byAssignee.size === 0) {
-		log.info("[projects-daily-digest] no new tasks in the last 24h — nothing to send");
-		return;
-	}
-
-	const orgNames = await loadOrgNames(prisma, [...new Set(tasks.map((t) => t.organisation_id))]);
-	const users = await loadUsers(prisma, [...byAssignee.keys()]);
-	const appUrl = await resolveAppBaseUrl();
-
-	let sent = 0;
-	for (const [userId, userTasks] of byAssignee) {
-		const user = users.get(userId);
-		if (!user?.email) continue;
-		const orgId = userTasks[0]!.organisation_id;
-		try {
-			const result = await emailClient.send({
-				to: user.email,
-				template: "projects-daily-digest",
-				vars: {
-					recipient_name: user.name || user.email,
-					org_name: orgNames.get(orgId) ?? "your organisation",
-					new_task_count: String(userTasks.length),
-					task_list_html: renderListHtml(userTasks, appUrl),
-					task_list_text: renderListText(userTasks),
-					app_url: `${appUrl}/${orgId}`,
-				},
-			});
-			if (result.status !== "failed") sent++;
-		} catch (err) {
-			log.error("[projects-daily-digest] send failed", { userId, error: err instanceof Error ? err.message : String(err) });
-		}
-	}
-	log.info(`[projects-daily-digest] complete — ${sent}/${byAssignee.size} digest(s) sent`);
-}
-
-export async function sendWeeklyDigest(_ctx: { config: ScheduledJobConfig }): Promise<void> {
-	const log = getAppLogger();
-	const prisma = getPrisma();
-	const now = new Date();
-	const weekAhead = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
-
-	const [overdue, upcoming] = await Promise.all([
-		prisma.work_items.findMany({
-			where: { kind: "task", completed: { not: true }, assignee_id: { not: null }, due_date: { lt: now } },
-			select: { id: true, title: true, organisation_id: true, assignee_id: true },
-		}) as Promise<DigestTask[]>,
-		prisma.work_items.findMany({
-			where: {
-				kind: "task",
-				completed: { not: true },
-				assignee_id: { not: null },
-				due_date: { gte: now, lte: weekAhead },
-			},
-			select: { id: true, title: true, organisation_id: true, assignee_id: true },
-		}) as Promise<DigestTask[]>,
-	]);
-
-	const overdueByAssignee = groupByAssignee(overdue);
-	const upcomingByAssignee = groupByAssignee(upcoming);
-	const assigneeIds = new Set([...overdueByAssignee.keys(), ...upcomingByAssignee.keys()]);
-	if (assigneeIds.size === 0) {
-		log.info("[projects-weekly-digest] nothing overdue or due this week — nothing to send");
-		return;
-	}
-
-	const allTasks = [...overdue, ...upcoming];
-	const orgNames = await loadOrgNames(prisma, [...new Set(allTasks.map((t) => t.organisation_id))]);
-	const users = await loadUsers(prisma, [...assigneeIds]);
-	const appUrl = await resolveAppBaseUrl();
-
-	let sent = 0;
-	for (const userId of assigneeIds) {
-		const user = users.get(userId);
-		if (!user?.email) continue;
-		const userOverdue = overdueByAssignee.get(userId) ?? [];
-		const userUpcoming = upcomingByAssignee.get(userId) ?? [];
-		const orgId = (userOverdue[0] ?? userUpcoming[0])!.organisation_id;
-		try {
-			const result = await emailClient.send({
-				to: user.email,
-				template: "projects-weekly-digest",
-				vars: {
-					recipient_name: user.name || user.email,
-					org_name: orgNames.get(orgId) ?? "your organisation",
-					overdue_count: String(userOverdue.length),
-					upcoming_count: String(userUpcoming.length),
-					overdue_list_html: renderListHtml(userOverdue, appUrl),
-					overdue_list_text: renderListText(userOverdue),
-					upcoming_list_html: renderListHtml(userUpcoming, appUrl),
-					upcoming_list_text: renderListText(userUpcoming),
-					app_url: `${appUrl}/${orgId}`,
-				},
-			});
-			if (result.status !== "failed") sent++;
-		} catch (err) {
-			log.error("[projects-weekly-digest] send failed", { userId, error: err instanceof Error ? err.message : String(err) });
-		}
-	}
-	log.info(`[projects-weekly-digest] complete — ${sent}/${assigneeIds.size} digest(s) sent`);
-}
-
-pgBossHandlerRegistry.register("@teamscala/service-boot:projects-daily-digest", sendDailyDigest);
-pgBossHandlerRegistry.register("@teamscala/service-boot:projects-weekly-digest", sendWeeklyDigest);

package/src/handlers/quiz-research.ts

@@ -1,178 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `quiz-research` pg-boss handler — the trigger + execution surface for the
- * quiz research pass (assessment_research). Two job shapes on one queue:
- *
- * - cron tick (jobData null, from the scheduled_job row's cron): the SWEEP —
- *   bounded batch of eligible responses (identity anchor present, within the
- *   window, no live pass, fewer than the attempt cap of superseded
- *   failure-tombstones) → one singleton-deduped one-shot job per response on
- *   this same queue. The submit path is never touched; research starts within
- *   one tick of the submit.
- * - `{ responseId }`: the RUN — one research pass via
- *   @teamscala/assessment's run unit; a throw lands in pg-boss native retry
- *   (retryLimit from the scheduled_job row).
- *
- * Tiering: this thin handler is server-tier (imports service-boot's own
- * getPgBoss + the adapters-tier assessment package — downward only); all
- * pipeline logic lives in the capability package.
- */
-
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-import { prisma as databasePrisma } from "@teamscala/db/database/client";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import {
-	QuizResearchConfigSchema,
-	makeProductionDeps,
-	recordResearchFailure,
-	runQuizResearch,
-	type QuizResearchConfig,
-} from "@teamscala/assessment/assessment-research-run";
-import { normaliseLinkedinIdentity } from "@teamscala/assessment/linkedin-identity";
-import { getPgBoss } from "../pg-boss-mount.ts";
-import { registerScheduledJobHandler } from "../pg-boss-handler-registry.ts";
-
-const ATTEMPT_CAP = 2;
-const ELIGIBLE_WINDOW_DAYS = 7;
-/** Per-tick dedup window for the one-shot send (singletonKey = responseId). */
-const SEND_DEDUP_SECONDS = 600;
-
-interface QuizResearchJobData {
-	responseId?: string;
-}
-
-async function sweepAndDispatch(
-	config: QuizResearchConfig,
-	queueName: string,
-): Promise<number> {
-	const log = getAppLogger();
-	const boss = getPgBoss();
-	if (!boss) {
-		log.warn("[quiz-research] sweep fired but no pg-boss instance is mounted — skipping tick");
-		return 0;
-	}
-	const windowStart = new Date(Date.now() - ELIGIBLE_WINDOW_DAYS * 24 * 60 * 60 * 1000);
-	const candidates = (await databasePrisma.assessment_responses.findMany({
-		where: { linkedin_url: { not: null }, completed_at: { gt: windowStart } },
-		select: {
-			id: true,
-			assessment_id: true,
-			linkedin_url: true,
-			completed_at: true,
-		},
-		orderBy: { completed_at: "desc" },
-		take: 200,
-	})) as unknown as Array<{
-		id: string;
-		assessment_id: string;
-		linkedin_url: string;
-	}>;
-
-	let dispatched = 0;
-	for (const candidate of candidates) {
-		if (dispatched >= (config.batch_size ?? 3)) break;
-		const identityKey = normaliseLinkedinIdentity(candidate.linkedin_url);
-		if (!identityKey) continue;
-		const researchRows = (await databasePrisma.assessment_research.findMany({
-			where: { assessment_id: candidate.assessment_id, identity_key: identityKey },
-			select: { superseded_at: true },
-			orderBy: { researched_at: "desc" },
-		})) as unknown as Array<{ superseded_at: Date | string | null }>;
-		if (researchRows.some((row) => row.superseded_at == null)) continue; // live pass exists
-		const tombstones = researchRows.filter((row) => row.superseded_at != null).length;
-		if (tombstones >= ATTEMPT_CAP) continue; // failed too many times — leave it
-		const sent = await boss.send(
-			queueName,
-			{ responseId: candidate.id } satisfies QuizResearchJobData,
-			{ singletonKey: candidate.id, singletonSeconds: SEND_DEDUP_SECONDS },
-		);
-		if (sent) dispatched++;
-	}
-	return dispatched;
-}
-
-async function quizResearchHandler(ctx: {
-	config: ScheduledJobConfig;
-	jobData?: unknown;
-}): Promise<unknown> {
-	const log = getAppLogger();
-	// "quiz-research" is not yet in the generated ConfigKey union: the registry-keys
-	// codegen output is refusing to regenerate (shrink-guard refusal, 2026-09-16) —
-	// surfaced to the orchestrator. The cast is the same boundary shape the sibling
-	// units use for dynamic slugs; drop it when the union regen lands.
-	const config = await loadRegistryConfig("config", "quiz-research" as never, QuizResearchConfigSchema) as unknown as QuizResearchConfig;
-	const queueName = ctx.config.queue_name;
-	const jobData = (ctx.jobData ?? {}) as QuizResearchJobData;
-
-	if (!jobData.responseId) {
-		const dispatched = await sweepAndDispatch(config, queueName);
-		return { mode: "sweep", dispatched };
-	}
-
-	const responseId = jobData.responseId;
-	try {
-		// The generated client does not structurally spell the simplified delegate shape
-		// ResearchPrisma declares (its method types are deeply generic); the boundary cast
-		// is the contained admission — the unit documents the exact calls it makes.
-		const result = await runQuizResearch(databasePrisma as unknown as never as Parameters<typeof runQuizResearch>[0], responseId, makeProductionDeps(config));
-		return { mode: "run", responseId, ...result };
-	} catch (err) {
-		const reason = err instanceof Error ? err.message : String(err);
-		// Attempt tombstone: a superseded, findings-less research row that the
-		// report can never render (only superseded_at IS NULL rows load) but the
-		// sweep can count — ATTEMPT_CAP failures stop further dispatch. Written
-		// on every failed invocation so pg-boss retries consume the cap too.
-		try {
-			const response = (await databasePrisma.assessment_responses.findUnique({
-				where: { id: responseId },
-				select: {
-					assessment_id: true,
-					organisation_id: true,
-					linkedin_url: true,
-					first_name: true,
-					last_name: true,
-				},
-			})) as unknown as {
-				assessment_id: string;
-				organisation_id: string | null;
-				linkedin_url: string | null;
-				first_name: string | null;
-				last_name: string | null;
-			} | null;
-			const identityKey = response?.linkedin_url
-				? normaliseLinkedinIdentity(response.linkedin_url)
-				: null;
-			if (response && identityKey) {
-				await databasePrisma.assessment_research.create({
-					data: {
-						assessment_id: response.assessment_id,
-						organisation_id: response.organisation_id,
-						display_name: [response.first_name, response.last_name]
-							.filter((p): p is string => typeof p === "string" && p.trim().length > 0)
-							.join(" ")
-							.trim() || "unresolved",
-						identity_key: identityKey,
-						linkedin_url: response.linkedin_url as string,
-						validation_note: `failed pass: ${reason.slice(0, 400)}`,
-						superseded_at: new Date(),
-						findings: {},
-					},
-					select: { id: true },
-				});
-			}
-		} catch (tombstoneErr) {
-			log.error(
-				`[quiz-research] tombstone write failed for ${responseId}: ${tombstoneErr instanceof Error ? tombstoneErr.message : String(tombstoneErr)}`,
-			);
-		}
-		recordResearchFailure(responseId, err);
-		log.error(`[quiz-research] pass failed for ${responseId}: ${reason}`);
-		throw err;
-	}
-}
-
-registerScheduledJobHandler("@teamscala/service-boot:quiz-research", quizResearchHandler);