@teamscala/service-boot 0.23.508 → 0.23.511

package/src/handlers/quiz-research.ts

@@ -0,0 +1,178 @@
+/**
+ * @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);

package/src/pg-boss-mount.ts

@@ -36,6 +36,8 @@ import "./handlers/scala-tools-currency-watch.ts";
 import "./handlers/singleton-tools-currency-watch.ts";
 import "./handlers/registry-stale-inactive-sweep.ts";
 import "./handlers/platform-fault-escalation.ts";
+import "./handlers/quiz-research.ts";
+
 
 /**
  * Module-level reference to the mounted PgBoss instance — set by mountPgBoss on