@teamscala/service-boot 0.23.472 → 0.23.473

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.472",
+  "version": "0.23.473",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -436,6 +436,22 @@
       "types": "./src/fn-routers/assessment-report-email.d.ts",
       "default": "./src/fn-routers/assessment-report-email.ts"
     },
+    "./fn-routers/assessment-report-pair": {
+      "types": "./src/fn-routers/assessment-report-pair.d.ts",
+      "default": "./src/fn-routers/assessment-report-pair.ts"
+    },
+    "./fn-routers/assessment-report-pair.ts": {
+      "types": "./src/fn-routers/assessment-report-pair.d.ts",
+      "default": "./src/fn-routers/assessment-report-pair.ts"
+    },
+    "./fn-routers/assessment-research-report-data": {
+      "types": "./src/fn-routers/assessment-research-report-data.d.ts",
+      "default": "./src/fn-routers/assessment-research-report-data.ts"
+    },
+    "./fn-routers/assessment-research-report-data.ts": {
+      "types": "./src/fn-routers/assessment-research-report-data.d.ts",
+      "default": "./src/fn-routers/assessment-research-report-data.ts"
+    },
     "./fn-routers/assessment-scoring": {
       "types": "./src/fn-routers/assessment-scoring.d.ts",
       "default": "./src/fn-routers/assessment-scoring.ts"
@@ -504,6 +520,14 @@
       "types": "./src/fn-routers/index.d.ts",
       "default": "./src/fn-routers/index.ts"
     },
+    "./fn-routers/linkedin-identity": {
+      "types": "./src/fn-routers/linkedin-identity.d.ts",
+      "default": "./src/fn-routers/linkedin-identity.ts"
+    },
+    "./fn-routers/linkedin-identity.ts": {
+      "types": "./src/fn-routers/linkedin-identity.d.ts",
+      "default": "./src/fn-routers/linkedin-identity.ts"
+    },
     "./fn-routers/messaging-whatsapp-router": {
       "types": "./src/fn-routers/messaging-whatsapp-router.d.ts",
       "default": "./src/fn-routers/messaging-whatsapp-router.ts"

package/src/fn-routers/assessment-report-data.ts

@@ -18,6 +18,13 @@
  * lives on `assessments.stage_bands` (migration 560/561).
  */
 
+import type { ReportResearchInput, ResearchReportData } from "./assessment-research-report-data.ts";
+import {
+	buildResearchReportData,
+	mergeNextSteps,
+	readResearchFindings,
+} from "./assessment-research-report-data.ts";
+
 /** A chart data point — structural match for @teamscala/chart-block's ChartPoint. */
 export interface ReportChartPoint {
 	label: string;
@@ -156,6 +163,8 @@ export interface ReportData {
 	twelveMonthTarget: string;
 	/** section 10 — three phases, each a focus word plus four actions */
 	roadmap: RoadmapPhase[];
+	/** the research half of the report — `{present:false}` when no research pass exists */
+	research: ResearchReportData;
 	/** Anna's remaining template elements — empty until a stage authors them. */
 	whoYouHelp: string;
 	knownFor: string;
@@ -180,6 +189,21 @@ export interface ReportResponseInput {
 	category_scores?: Record<string, number> | null;
 }
 
+/**
+ * The response fields the paired report needs beyond the score: the person's
+ * names (prepared-for line) and the LinkedIn URL the research pairing
+ * normalises.
+ */
+export interface ReportPairResponseShape extends ReportResponseInput {
+	id?: string;
+	assessment_id?: string;
+	first_name?: string | null;
+	last_name?: string | null;
+	linkedin_url?: string | null;
+	website?: string | null;
+	completed_at?: Date | string | null;
+}
+
 /** Minimal view of the assessment metadata — title plus the stage model. */
 export interface ReportAssessmentInput {
 	title?: string | null;
@@ -318,20 +342,45 @@ export function orderRoadmap(roadmap: Record<string, RoadmapPhase> | undefined):
  * `fn({ input, client, params })` (see resolveByResolverFn in
  * @teamscala/service-boot/resolve-from-loader-config). computeReportData is
  * registered as the `computeReportData` resolver_fn row, so it receives that
- * context — input.response / input.assessment come from the loader's
- * resolver_input ({response: ':response', assessment: ':assessment'}).
+ * context — input.response / input.research / input.assessment come from the
+ * loader's resolver_input, already PAIRED by the resolveReportHalves resolver
+ * (research attaches to a response by normalised LinkedIn identity — both
+ * halves resolved, or the research half alone for a research-only person).
  */
 export function computeReportData({
 	input,
 }: {
 	input: {
-		response?: ReportResponseInput | null;
+		response?: ReportPairResponseShape | null;
 		assessment?: ReportAssessmentInput | null;
+		research?: ReportResearchInput | null;
+		brandName?: string | null;
 	};
 }): ReportData {
 	const { response, assessment } = input;
-	const totalScore = Math.max(0, Math.round(Number(response?.total_score ?? 0)));
-	const categoryScores = response?.category_scores ?? {};
+	const research = input.research ?? null;
+	const bands = readStageBands(assessment);
+	const researchData = buildResearchReportData({
+		research,
+		response,
+		assessment,
+		bands,
+		resolveBand: (score: number) => selectStageBand(bands, score),
+		brandName: input.brandName,
+	});
+	// Research-only reports (no quiz response) take their headline score from
+	// the research pass so the Snapshot and pillar sections render from the
+	// only scoring that exists; both halves present, the response stays the
+	// subject of section one and the research feeds sections two through five.
+	const scores = response ??
+		(research
+			? {
+					total_score: research.total_score,
+					category_scores: research.category_scores,
+				}
+			: null);
+	const totalScore = Math.max(0, Math.round(Number(scores?.total_score ?? 0)));
+	const categoryScores = scores?.category_scores ?? {};
 	const reportScore: ReportChartPoint[] = [{ label: "Score", value: totalScore }];
 	const reportPillars: ReportChartPoint[] = Object.entries(categoryScores)
 		.filter(([, value]) => Number.isFinite(Number(value)))
@@ -339,8 +388,13 @@ export function computeReportData({
 		.filter((p) => p.label.length > 0)
 		.sort((a, b) => b.value - a.value);
 
-	const band = selectStageBand(readStageBands(assessment), totalScore);
-	const narrative = generateNarrative(totalScore, band, assessment);
+	const band = selectStageBand(bands, totalScore);
+	const findings = research ? readResearchFindings(research.findings) : {};
+	const nextSteps = research ? mergeNextSteps(band, findings) : null;
+	const narrative =
+		research && !response && researchData.execSummary
+			? researchData.execSummary
+			: generateNarrative(totalScore, band, assessment);
 	const pillarCards = buildPillarCards(assessment, categoryScores, band);
 	// The chart bars take each pillar's own colour, so the bar chart and the
 	// pillar cards cannot disagree about which colour means which pillar.
@@ -395,15 +449,26 @@ export function computeReportData({
 		strongest,
 		opportunity,
 		authorityGap,
-		strongestAreas: band?.strongestAreas ?? [],
-		priorityActions: band?.priorityActions ?? [],
-		strategicFocus: band?.strategicFocus ?? "",
-		strengths: band?.strengths ?? [],
-		opportunities: band?.opportunities ?? [],
-		strengthsList: numberItems(band?.strengths),
-		opportunitiesList: numberItems(band?.opportunities),
-		twelveMonthTarget: band?.twelveMonthTarget ?? "",
-		roadmap: orderRoadmap(band?.roadmap),
+		// Section five: the research pass's person-specific content wins
+		// field-by-field; without research these are the band's copy, exactly
+		// as every report before this table rendered them.
+		strongestAreas: nextSteps?.strongestAreas ?? band?.strongestAreas ?? [],
+		priorityActions: nextSteps?.priorityActions ?? band?.priorityActions ?? [],
+		strategicFocus: nextSteps?.strategicFocus ?? band?.strategicFocus ?? "",
+		strengths: nextSteps?.strengths ?? band?.strengths ?? [],
+		opportunities: nextSteps?.opportunities ?? band?.opportunities ?? [],
+		strengthsList: numberItems(nextSteps?.strengths ?? band?.strengths),
+		opportunitiesList: numberItems(nextSteps?.opportunities ?? band?.opportunities),
+		twelveMonthTarget: nextSteps?.twelveMonthTarget ?? band?.twelveMonthTarget ?? "",
+		roadmap: nextSteps?.roadmap ?? orderRoadmap(band?.roadmap),
+		research: {
+			...researchData,
+			groups: researchData.groups.map((group) => ({
+				title: group.title,
+				items: numberItems(group.items),
+			})),
+			weakestAreasList: numberItems(researchData.weakestAreas),
+		},
 		whoYouHelp: band?.whoYouHelp ?? "",
 		knownFor: band?.knownFor ?? "",
 		insights: band?.insights ?? [],

package/src/fn-routers/assessment-report-pair.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import { resolveReportHalves } from "./assessment-report-pair.ts";
+import type { ReportResearchInput } from "./assessment-research-report-data.ts";
+
+const ANNA_LINKEDIN_RAW = "https://www.linkedin.com/in/annaosherov/";
+const ANNA_KEY = "linkedin.com/in/annaosherov";
+
+function annaResearch(overrides: Partial<ReportResearchInput> = {}): ReportResearchInput {
+	return {
+		id: "research-anna",
+		assessment_id: "assessment-launcha",
+		display_name: "Anna Osherov",
+		linkedin_url: ANNA_LINKEDIN_RAW,
+		identity_key: ANNA_KEY,
+		validation_note: "Confirmed.",
+		total_score: 71,
+		category_scores: { "Be Seen": 57, "Be Heard": 76, "Be Chosen": 80 },
+		researched_at: "2026-09-04T00:00:00Z",
+		superseded_at: null,
+		...overrides,
+	};
+}
+
+const ANNA_RESPONSE = {
+	id: "response-anna",
+	assessment_id: "assessment-launcha",
+	first_name: "Anna",
+	linkedin_url: ANNA_LINKEDIN_RAW,
+	total_score: 54,
+};
+
+function fakeClient(overrides: {
+	researchLive?: ReportResearchInput | null;
+	responses?: Array<{ linkedin_url: string | null } & Record<string, unknown>>;
+}) {
+	return {
+		assessment_research: {
+			findFirst: async () => overrides.researchLive ?? null,
+		},
+		assessment_responses: {
+			findFirst: async () => null,
+			findMany: async () => overrides.responses ?? [],
+		},
+	};
+}
+
+describe("resolveReportHalves", () => {
+	test("response-anchored :id pairs the research by normalised identity", async () => {
+		const halves = await resolveReportHalves({
+			input: { response: ANNA_RESPONSE, research: null, id: "response-anna" },
+			client: fakeClient({ researchLive: annaResearch() }),
+			params: {},
+		});
+		expect(halves.research?.identity_key).toBe(ANNA_KEY);
+	});
+
+	test("research-anchored :id pairs the quiz response by normalised identity", async () => {
+		const halves = await resolveReportHalves({
+			input: { response: null, research: annaResearch(), id: "research-anna" },
+			client: fakeClient({
+				responses: [
+					{ id: "response-anna", linkedin_url: ANNA_LINKEDIN_RAW, total_score: 54 },
+				],
+			}),
+			params: {},
+		});
+		expect(halves.response?.id).toBe("response-anna");
+	});
+
+	test("a different person's response is never paired", async () => {
+		const halves = await resolveReportHalves({
+			input: { response: null, research: annaResearch(), id: "research-anna" },
+			client: fakeClient({
+				responses: [
+					{
+						id: "response-other",
+						linkedin_url: "https://www.linkedin.com/in/malcolm-mclean/",
+						total_score: 12,
+					},
+				],
+			}),
+			params: {},
+		});
+		expect(halves.response).toBeNull();
+	});
+
+	test("a superseded anchor resolves the person's live pass", async () => {
+		const superseded = annaResearch({ superseded_at: "2026-09-04T01:00:00Z" });
+		const halves = await resolveReportHalves({
+			input: { response: null, research: superseded, id: "research-superseded" },
+			client: fakeClient({ researchLive: annaResearch() }),
+			params: {},
+		});
+		expect(halves.research?.superseded_at).toBeNull();
+		expect(halves.research?.total_score).toBe(71);
+	});
+
+	test("an id matching neither surface refuses instead of rendering an empty report", async () => {
+		await expect(
+			resolveReportHalves({
+				input: { response: null, research: null, id: "unknown-id" },
+				client: fakeClient({}),
+				params: {},
+			}),
+		).rejects.toThrow(/matches no quiz response/);
+	});
+});

package/src/fn-routers/assessment-report-pair.ts

@@ -0,0 +1,155 @@
+/**
+ * @system service-boot
+ * @status handwritten @indivisible-unit owner=lane/unified-authority-index-report reason="one pairing unit: the rule that joins a report id to its response+research halves lives here alone"
+ * @edit edit directly
+ *
+ * assessment-report-pair.ts — resolveReportHalves resolver_fn.
+ *
+ * /report/:id carries EITHER an assessment_responses id OR an
+ * assessment_research id. This resolver turns whichever anchor arrived into
+ * the complete PAIR by the person's normalised LinkedIn identity
+ * (identity_key, shared unit in linkedin-identity.ts) per assessment — so
+ * both URL forms render identical content, and a quiz response (re)taken
+ * after research still pairs with that person's research.
+ *
+ * WHY A RESOLVER AND NOT LOADER SOURCES: the join key is a DERIVED value
+ * (the normalised URL), not a column equality a row config can express, and
+ * the response side stores raw self-reported URLs. The resolver owns the
+ * lookup; the loader row stays declarative.
+ *
+ * SUPERSEDED PASSES NEVER REACH A READER (operator correction 2026-09-04): a
+ * research pass can be WRONG and get corrected; the superseded row keeps its
+ * history but the report resolves the live pass (superseded_at IS NULL) even
+ * when the :id anchor points at the superseded one, so an old link renders
+ * the corrected report, never the withdrawn one.
+ */
+import { normaliseLinkedinIdentity } from "./linkedin-identity.ts";
+import type { ReportPairResponseInput, ReportResearchInput } from "./assessment-research-report-data.ts";
+
+const RESEARCH_SELECT = {
+	id: true,
+	assessment_id: true,
+	display_name: true,
+	role_line: true,
+	linkedin_url: true,
+	identity_key: true,
+	website: true,
+	organisation_id: true,
+	validation_note: true,
+	total_score: true,
+	category_scores: true,
+	answers: true,
+	findings: true,
+	researched_at: true,
+	superseded_at: true,
+} as const;
+
+const RESPONSE_SELECT = {
+	id: true,
+	assessment_id: true,
+	first_name: true,
+	last_name: true,
+	linkedin_url: true,
+	website: true,
+	total_score: true,
+	category_scores: true,
+	answers: true,
+	completed_at: true,
+	organisation_id: true,
+} as const;
+
+interface ResearchDelegate {
+	findFirst: (args: {
+		where: Record<string, unknown>;
+		select: typeof RESEARCH_SELECT;
+	}) => Promise<ReportResearchInput | null>;
+}
+
+interface ResponseDelegate {
+	findFirst: (args: {
+		where: Record<string, unknown>;
+		select: typeof RESPONSE_SELECT;
+	}) => Promise<ReportPairResponseInput | null>;
+	findMany: (args: {
+		where: Record<string, unknown>;
+		select: typeof RESPONSE_SELECT;
+		orderBy?: Record<string, string>;
+		take?: number;
+	}) => Promise<Array<ReportPairResponseInput & { linkedin_url: string | null }>>;
+}
+
+export interface ReportHalves {
+	response: ReportPairResponseInput | null;
+	research: ReportResearchInput | null;
+}
+
+export async function resolveReportHalves({
+	input,
+	client,
+}: {
+	input: {
+		response?: ReportPairResponseInput | null;
+		research?: ReportResearchInput | null;
+		id?: string;
+	};
+	client: unknown;
+	params: Record<string, unknown>;
+}): Promise<ReportHalves> {
+	let response = input.response ?? null;
+	let research = input.research ?? null;
+	const prisma = client as {
+		assessment_research?: ResearchDelegate;
+		assessment_responses?: ResponseDelegate;
+	};
+
+	// A superseded anchor resolves to the person's LIVE pass — an old link
+	// must render the corrected report, never the withdrawn one.
+	if (research && research.superseded_at != null) {
+		research = (await prisma.assessment_research?.findFirst({
+			where: {
+				assessment_id: research.assessment_id,
+				identity_key: research.identity_key,
+				superseded_at: null,
+			},
+			select: RESEARCH_SELECT,
+		})) ?? null;
+	}
+
+	if (response && !research) {
+		const identityKey = normaliseLinkedinIdentity(response.linkedin_url);
+		if (identityKey) {
+			research = (await prisma.assessment_research?.findFirst({
+				where: {
+					assessment_id: response.assessment_id,
+					identity_key: identityKey,
+					superseded_at: null,
+				},
+				select: RESEARCH_SELECT,
+			})) ?? null;
+		}
+	} else if (research && !response) {
+		// Research-only :id — find this person's quiz response by normalised
+		// identity. The response side stores raw self-reported URLs, so the
+		// normalisation must run per candidate; ordered by recency so a
+		// (re)taken quiz pairs with the latest submission.
+		const candidates = (await prisma.assessment_responses?.findMany({
+			where: { assessment_id: research.assessment_id, linkedin_url: { not: null } },
+			select: RESPONSE_SELECT,
+			orderBy: { completed_at: "desc" },
+			take: 25,
+		})) ?? [];
+		response =
+			candidates.find(
+				(candidate) =>
+					normaliseLinkedinIdentity(candidate.linkedin_url) === research?.identity_key,
+			) ?? null;
+	}
+
+	if (!response && !research) {
+		throw new Error(
+			`[assessment-report] /report/${input.id ?? ""} matches no quiz response and no research record — check the id`,
+		);
+	}
+
+	return { response, research };
+}

package/src/fn-routers/assessment-research-report-data.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildCombinedStatement,
+	buildPreparedFor,
+	buildResearchReportData,
+	gapText,
+	readResearchFindings,
+	type ReportResearchInput,
+} from "./assessment-research-report-data.ts";
+import { normaliseLinkedinIdentity } from "./linkedin-identity.ts";
+import {
+	computeReportData,
+	selectStageBand,
+	type ReportAssessmentInput,
+	type StageBand,
+} from "./assessment-report-data.ts";
+
+const ANNA_LINKEDIN_RAW = "https://www.linkedin.com/in/annaosherov/";
+const ANNA_KEY = "linkedin.com/in/annaosherov";
+
+const STAGE_BANDS: StageBand[] = [
+	{ name: "Unknown", max: 20 },
+	{ name: "Testing", max: 40 },
+	{ name: "Experimenting", max: 60 },
+	{ name: "Recognised", max: 80 },
+	{ name: "Industry Influencer" },
+];
+
+const ASSESSMENT: ReportAssessmentInput = {
+	title: "The Launcha Authority Index",
+	categories: ["Be Seen", "Be Heard", "Be Chosen"],
+	category_descriptions: {
+		"Be Seen": { subtitle: "Visibility + Positioning", color: "#2563eb" },
+		"Be Heard": { subtitle: "Credibility + Trust", color: "#FF4500" },
+		"Be Chosen": { subtitle: "Leads + Conversion", color: "#16a34a" },
+	},
+	stage_bands: { bands: STAGE_BANDS },
+};
+
+const ANNA_RESPONSE = {
+	id: "response-anna",
+	assessment_id: "assessment-launcha",
+	first_name: "Anna",
+	last_name: "Osherov",
+	linkedin_url: ANNA_LINKEDIN_RAW,
+	total_score: 54,
+	category_scores: { "Be Seen": 43, "Be Heard": 57, "Be Chosen": 63 },
+	completed_at: "2026-09-01T00:00:00Z",
+};
+
+function annaResearch(overrides: Partial<ReportResearchInput> = {}): ReportResearchInput {
+	return {
+		id: "research-anna",
+		assessment_id: "assessment-launcha",
+		display_name: "Anna Osherov",
+		role_line: "CEO, Launcha",
+		linkedin_url: ANNA_LINKEDIN_RAW,
+		identity_key: ANNA_KEY,
+		organisation_id: "org-launcha",
+		validation_note:
+			"Confirmed against linkedin.com/in/annaosherov — five sources agree; the materials scientist who shares the name is excluded entirely.",
+		total_score: 71,
+		category_scores: { "Be Seen": 57, "Be Heard": 76, "Be Chosen": 80 },
+		findings: {
+			execSummary: "Measured from public evidence, you sit a full band higher than you think.",
+			intro: "Your LinkedIn profile is the anchor for everything counted here.",
+			groups: [
+				{ title: "Websites", items: ["launcha.marketing is live, current, and identifies you"] },
+			],
+			claims: [
+				{
+					question: "I regularly appear on stages, podcasts, or other people's platforms.",
+					selfValue: "1 / 5",
+					evidenceValue: "5 / 5",
+					why: "Two podcasts and seven years of MC work say otherwise.",
+				},
+			],
+			weakestAreas: ["A name search you do not own"],
+			strategicFocus: "Convert proof you already own into surface you control.",
+			sourceSummary: "Sources · linkedin.com/in/annaosherov · launcha.marketing",
+		},
+		researched_at: "2026-09-04T00:00:00Z",
+		...overrides,
+	};
+}
+
+describe("normaliseLinkedinIdentity", () => {
+	test("collapses every spelling of the same profile to one key", () => {
+		expect(normaliseLinkedinIdentity(ANNA_LINKEDIN_RAW)).toBe(ANNA_KEY);
+		expect(normaliseLinkedinIdentity("linkedin.com/in/AnnaOsherov")).toBe(ANNA_KEY);
+		expect(normaliseLinkedinIdentity("  LinkedIn.com/in/annaosherov/ ")).toBe(ANNA_KEY);
+	});
+
+	test("refuses non-linkedin and empty input rather than guessing a key", () => {
+		expect(normaliseLinkedinIdentity("https://example.com/in/someone")).toBeNull();
+		expect(normaliseLinkedinIdentity("   ")).toBeNull();
+		expect(normaliseLinkedinIdentity(null)).toBeNull();
+	});
+});
+
+describe("research shaping", () => {
+	test("shapes the five-section research half: identity, findings, gaps, combined standing", () => {
+		const data = computeReportData({
+			input: {
+				response: ANNA_RESPONSE,
+				research: annaResearch(),
+				assessment: ASSESSMENT,
+				brandName: "Launcha Marketing",
+			},
+		});
+
+		expect(data.research.present).toBe(true);
+		expect(data.research.hasSelfResponse).toBe(true);
+		expect(data.research.preparedFor).toBe("Launcha Marketing and Anna Osherov");
+		expect(data.research.identifiedBy).toBe(ANNA_LINKEDIN_RAW);
+		expect(data.research.validationStatement).toContain("excluded");
+		expect(data.research.groups[0]?.title).toBe("Websites");
+		expect(data.research.claims[0]?.question).toContain("stages, podcasts");
+
+		const overall = data.research.gapRows.at(-1);
+		expect(overall).toEqual({
+			label: "Overall",
+			subtitle: "",
+			self: "54",
+			found: "71",
+			gap: "+17",
+		});
+		expect(data.research.combinedStatement).toContain("17 points higher");
+		expect(data.research.combinedBand).toBe("Recognised");
+		expect(data.research.reportDate).toBe("2026-09-01");
+	});
+
+	test("research-only person: the research score drives the snapshot and the self sections stay absent", () => {
+		const data = computeReportData({
+			input: {
+				response: null,
+				research: annaResearch(),
+				assessment: ASSESSMENT,
+				brandName: "Launcha Marketing",
+			},
+		});
+		expect(data.totalScore).toBe(71);
+		expect(data.research.hasSelfResponse).toBe(false);
+		expect(data.research.gapRows).toEqual([]);
+		expect(data.narrative).toBe(
+			"Measured from public evidence, you sit a full band higher than you think.",
+		);
+	});
+
+	test("person-specific next steps win field-by-field; the band copy fills the rest", () => {
+		const data = computeReportData({
+			input: {
+				response: ANNA_RESPONSE,
+				research: annaResearch(),
+				assessment: ASSESSMENT,
+			},
+		});
+		expect(data.strategicFocus).toBe(
+			"Convert proof you already own into surface you control.",
+		);
+		expect(data.strongestAreas).toEqual([]);
+	});
+
+	test("a superseded research pass is refused — it must never shape a report", () => {
+		expect(() =>
+			buildResearchReportData({
+				research: annaResearch({ superseded_at: "2026-09-04T01:00:00Z" }),
+				response: ANNA_RESPONSE,
+				assessment: ASSESSMENT,
+				bands: STAGE_BANDS,
+				resolveBand: (score) => selectStageBand(STAGE_BANDS, score),
+			}),
+		).toThrow(/superseded/);
+	});
+
+	test("malformed authored findings throw instead of silently rendering garbage", () => {
+		expect(() => readResearchFindings({ groups: "not-an-array" })).toThrow();
+	});
+});
+
+describe("the rendered text surface is one-person clean", () => {
+	// The report page is a pure projection of the loaderData strings: every
+	// block binds a fieldPath into reportData/response/quiz, so the rendered
+	// text cannot contain anything these strings do not. Serialising every
+	// string leaf of the shaped report therefore exercises exactly the text
+	// the page can render.
+
+	function collectStrings(value: unknown, out: string[] = []): string[] {
+		if (typeof value === "string") {
+			out.push(value);
+		} else if (Array.isArray(value)) {
+			for (const item of value) collectStrings(item, out);
+		} else if (value != null && typeof value === "object") {
+			for (const item of Object.values(value)) collectStrings(item, out);
+		}
+		return out;
+	}
+
+	const OTHER_PERSON_MARKERS = ["Malcolm McLean", "malcolm", "McLean"];
+	const GHL_MARKERS = ["GoHighLevel", "ghl_contact", "ghl_", "leadconnectorhq"];
+
+	test("Anna's report carries no second person's name and no GoHighLevel tag", () => {
+		const data = computeReportData({
+			input: {
+				// the loader select deliberately excludes the ghl_* columns; this
+				// response shape is exactly what the row select delivers
+				response: ANNA_RESPONSE,
+				research: annaResearch(),
+				assessment: ASSESSMENT,
+				brandName: "Launcha Marketing",
+			},
+		});
+		const strings = collectStrings(data).join(" \n ");
+		for (const marker of OTHER_PERSON_MARKERS) {
+			expect(strings).not.toContain(marker);
+		}
+		for (const marker of GHL_MARKERS) {
+			expect(strings).not.toContain(marker);
+		}
+	});
+
+	// "a different person's research never renders here" is enforced UPSTREAM:
+	// the pairing resolver matches halves by normalised LinkedIn identity, and
+	// its refusal tests live in fn-routers/assessment-report-pair.test.ts.
+});
+
+describe("small derivations", () => {
+	test("gapText is signed and plain", () => {
+		expect(gapText(54, 71)).toBe("+17");
+		expect(gapText(71, 54)).toBe("-17");
+		expect(gapText(54, 54)).toBe("0");
+	});
+
+	test("prepared-for line reads exactly brand and person", () => {
+		expect(buildPreparedFor("Launcha Marketing", "Anna Osherov")).toBe(
+			"Launcha Marketing and Anna Osherov",
+		);
+	});
+
+	test("combined statement names the direction, size and band", () => {
+		const statement = buildCombinedStatement({
+			selfScore: 54,
+			researchScore: 71,
+			bandSteps: 1,
+			researchBandName: "Recognised",
+		});
+		expect(statement).toContain("17 points higher");
+		expect(statement).toContain("one band higher");
+		expect(statement).toContain("Recognised");
+	});
+});

package/src/fn-routers/assessment-research-report-data.ts

@@ -0,0 +1,421 @@
+/**
+ * @system service-boot
+ * @status handwritten @indivisible-unit owner=lane/unified-authority-index-report reason="one research-shaping unit: findings validation, gap derivation and next-step precedence change together"
+ * @edit edit directly
+ *
+ * assessment-research-report-data.ts — research pass → report data.
+ *
+ * Shapes a stored `assessment_research` row into the report fields the quiz
+ * report page renders for the research half (sections: what we found online,
+ * where you stand, why, and the research-authored next steps). The findings
+ * JSONB is AUTHORING DATA owned by the research pass; this unit validates it
+ * against the db-validation contract and derives only what derivation owes —
+ * the per-pillar gap table, the combined band statement and the merged
+ * next-steps — never new opinions about the person.
+ *
+ * PAIRING (see linkedin-identity.ts): research attaches to a quiz response by
+ * normalised LinkedIn identity per assessment, never by being a response row.
+ * A superseded pass never reaches a reader: the caller resolves the live pass
+ * (superseded_at IS NULL) and this unit re-checks, refusing to shape a
+ * superseded record into a report.
+ *
+ * NEXT-STEPS PRECEDENCE: the research pass authors per-person next steps;
+ * the assessment's stage bands author per-band copy. When both exist the
+ * research wins field-by-field (findings.strongestAreas ?? band.strongestAreas)
+ * so a person-specific finding can refine — never be overridden by — generic
+ * band advice, and an omitted field falls through to the band.
+ */
+
+import * as v from "valibot";
+import {
+	assessmentResearchFindingsSchema,
+} from "@teamscala/db-validation/generated/assessment-research-findings";
+import type {
+	ReportAssessmentInput,
+	ReportData,
+	StageBand,
+	TitledAction,
+} from "./assessment-report-data.ts";
+import { normaliseLinkedinIdentity } from "./linkedin-identity.ts";
+
+/** One authored contrast: the question, both sides, and the reasoning. */
+export interface ResearchClaim {
+	question: string;
+	selfValue: string;
+	evidenceValue: string;
+	why: string;
+}
+
+/** One authored findings group (websites, visibility, media, frictions, …). */
+export interface ResearchGroup {
+	title: string;
+	items: string[];
+}
+
+/** The authored findings blob on `assessment_research.findings`. */
+export interface ResearchFindings {
+	execSummary?: string;
+	intro?: string;
+	calloutTitle?: string;
+	calloutBody?: string;
+	groups?: ResearchGroup[];
+	claims?: ResearchClaim[];
+	weakestAreas?: string[];
+	strongestAreas?: string[];
+	priorityActions?: TitledAction[];
+	strategicFocus?: string;
+	strengths?: string[];
+	opportunities?: string[];
+	twelveMonthTarget?: string;
+	sprintPhases?: Array<{ days: string; focus: string; actions: string[] }>;
+	rawScoresNote?: string;
+	sourceSummary?: string;
+}
+
+/** Minimal view of a live assessment_research row as the loader selects it. */
+export interface ReportResearchInput {
+	id: string;
+	assessment_id: string;
+	display_name: string;
+	role_line?: string | null;
+	linkedin_url: string;
+	identity_key: string;
+	website?: string | null;
+	organisation_id?: string | null;
+	validation_note: string;
+	total_score?: number | null;
+	category_scores?: Record<string, number> | null;
+	answers?: unknown;
+	findings?: unknown;
+	researched_at?: Date | string | null;
+	superseded_at?: Date | string | null;
+}
+
+/** Extended response view: the identity fields the pairing reads. */
+export interface ReportPairResponseInput {
+	id: string;
+	assessment_id: string;
+	first_name?: string | null;
+	last_name?: string | null;
+	linkedin_url?: string | null;
+	website?: string | null;
+	total_score?: number | null;
+	category_scores?: Record<string, number> | null;
+	completed_at?: Date | string | null;
+}
+
+/**
+ * Validate authored findings against the db-validation contract. Returns {}
+ * for absent findings; THROWS for malformed findings — authored content that
+ * does not match the schema is a writer defect to surface, not an empty
+ * section to silently render.
+ */
+export function readResearchFindings(raw: unknown): ResearchFindings {
+	if (raw == null) return {};
+	const parsed = v.parse(
+		assessmentResearchFindingsSchema,
+		raw,
+	) as unknown as ResearchFindings;
+	return parsed;
+}
+
+/** A research row may shape a report only while it is the live pass. */
+export function assertLiveResearch(research: ReportResearchInput | null | undefined): void {
+	if (research && research.superseded_at != null) {
+		throw new Error(
+			`[assessment-research] research pass ${research.id} is superseded (${String(research.superseded_at)}) and must never render — resolve the live pass (superseded_at IS NULL) for this person`,
+		);
+	}
+}
+
+/** The person's display name: quiz response names first, research second. */
+export function resolvePersonName(
+	response: ReportPairResponseInput | null | undefined,
+	research: ReportResearchInput | null | undefined,
+): string {
+	const fromResponse = [response?.first_name, response?.last_name]
+		.filter((part): part is string => typeof part === "string" && part.trim().length > 0)
+		.join(" ")
+		.trim();
+	if (fromResponse.length > 0) return fromResponse;
+	const fromResearch = research?.display_name?.trim();
+	return fromResearch ?? "";
+}
+
+/**
+ * The prepared-for line, exactly: `<brand> and <person>`. Brand first, as the
+ * report is prepared FOR the brand about the person.
+ */
+export function buildPreparedFor(brandName: string, personName: string): string {
+	const brand = brandName.trim();
+	const person = personName.trim();
+	if (brand.length === 0) return person;
+	if (person.length === 0) return brand;
+	return `${brand} and ${person}`;
+}
+
+function numberOrZero(value: number | null | undefined): number {
+	const n = Number(value);
+	return Number.isFinite(n) ? Math.max(0, Math.round(n)) : 0;
+}
+
+/** Signed, plain gap text: "+14" / "-3" / "0". */
+export function gapText(self: number, found: number): string {
+	const delta = found - self;
+	return delta > 0 ? `+${delta}` : String(delta);
+}
+
+export interface GapRow {
+	label: string;
+	subtitle: string;
+	self: string;
+	found: string;
+	gap: string;
+}
+
+const BAND_STEP_WORDS = ["zero", "one", "two", "three", "four", "five"];
+
+/**
+ * The combined standing statement, assembled from the numbers and band
+ * positions the caller derives (it owns band selection): "Measured against
+ * the evidence, you sit 17 points higher than you placed yourself — one band
+ * higher, in Recognised."
+ */
+export function buildCombinedStatement(opts: {
+	selfScore: number;
+	researchScore: number;
+	/** band count between self and research: >0 when the band moved */
+	bandSteps: number;
+	researchBandName: string;
+}): string {
+	const { selfScore, researchScore, bandSteps, researchBandName } = opts;
+	const delta = researchScore - selfScore;
+	if (delta === 0) {
+		return "Measured against the evidence, the evidence agrees with where you placed yourself.";
+	}
+	const direction = delta > 0 ? "higher" : "lower";
+	let bandClause = "";
+	if (bandSteps !== 0) {
+		const word = BAND_STEP_WORDS[Math.abs(bandSteps)] ?? String(Math.abs(bandSteps));
+		bandClause = `, ${word} band${Math.abs(bandSteps) === 1 ? "" : "s"} ${direction}${researchBandName ? `, in ${researchBandName}` : ""}`;
+	}
+	return `Measured against the evidence, you sit ${Math.abs(delta)} points ${direction} than you placed yourself${bandClause}.`;
+}
+
+/** Resolved research half of a report — bound as `reportData.research` fields. */
+export interface ResearchReportData {
+	present: boolean;
+	/** true when a quiz response also exists — section one renders only then */
+	hasSelfResponse: boolean;
+	personName: string;
+	preparedFor: string;
+	identifiedBy: string;
+	validationStatement: string;
+	roleLine: string;
+	execSummary: string;
+	intro: string;
+	calloutTitle: string;
+	calloutBody: string;
+	groups: Array<{ title: string; items: Array<{ index: string; text: string }> }>;
+	claims: ResearchClaim[];
+	gapRows: GapRow[];
+	combinedBand: string;
+	combinedDelta: string;
+	combinedStatement: string;
+	weakestAreas: string[];
+	methodRawScores: string;
+	methodSources: string;
+	researchedAt: string;
+	/** the report's date: the quiz completion when a response exists, else the research date */
+	reportDate: string;
+}
+
+function isoDay(value: Date | string | null | undefined): string {
+	if (value == null) return "";
+	const d = value instanceof Date ? value : new Date(value);
+	if (Number.isNaN(d.getTime())) return "";
+	return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Shape the research half. When research is absent the result is
+ * `{ present: false, …empty }` — callers bind the quiz-only report exactly as
+ * before, and the page hides the research sections with visibleWhenPath.
+ *
+ * `resolveBand` is the caller's own band selector (selectStageBand over the
+ * assessment's parsed bands) injected rather than imported — the band
+ * primitives stay single-homed in assessment-report-data and this unit keeps
+ * no runtime dependency on it.
+ */
+export function buildResearchReportData(opts: {
+	research: ReportResearchInput | null | undefined;
+	response: ReportPairResponseInput | null | undefined;
+	assessment: ReportAssessmentInput | null | undefined;
+	resolveBand: (score: number) => StageBand | null;
+	/** the parsed bands, for band-distance derivation */
+	bands: StageBand[];
+	brandName?: string | null;
+}): ResearchReportData {
+	const { research, response, assessment } = opts;
+	const resolveBand = opts.resolveBand;
+	const bands = opts.bands;
+	const brandName = opts.brandName?.trim() ?? "";
+	const personName = resolvePersonName(response, research);
+	const preparedFor = buildPreparedFor(brandName, personName);
+
+	const empty: ResearchReportData = {
+		present: false,
+		hasSelfResponse: response != null,
+		personName,
+		preparedFor,
+		identifiedBy: "",
+		validationStatement: "",
+		roleLine: "",
+		execSummary: "",
+		intro: "",
+		calloutTitle: "",
+		calloutBody: "",
+		groups: [],
+		claims: [],
+		gapRows: [],
+		combinedBand: "",
+		combinedDelta: "",
+		combinedStatement: "",
+		weakestAreas: [],
+		methodRawScores: "",
+		methodSources: "",
+		researchedAt: "",
+		reportDate: "",
+	};
+	if (!research) return empty;
+
+	assertLiveResearch(research);
+
+	const findings = readResearchFindings(research.findings);
+
+	const selfScores: Record<string, number> = response?.category_scores ?? {};
+	const foundScores: Record<string, number> = research.category_scores ?? {};
+	const categories = Array.isArray(assessment?.categories)
+		? (assessment.categories as unknown[]).filter(
+				(c): c is string => typeof c === "string" && c.length > 0,
+			)
+		: Object.keys(foundScores);
+
+	const gapRows: GapRow[] = [];
+	if (response) {
+		for (const label of categories) {
+			const self = selfScores[label];
+			const found = numberOrZero(foundScores[label]);
+			const display = (assessment?.category_descriptions &&
+				typeof assessment.category_descriptions === "object"
+				? (assessment.category_descriptions as Record<string, { subtitle?: string }>)
+				: {})[label];
+			gapRows.push({
+				label,
+				subtitle: display?.subtitle ?? "",
+				self: typeof self === "number" ? String(Math.round(self)) : "—",
+				found: String(found),
+				gap: typeof self === "number" ? gapText(Math.round(self), found) : "—",
+			});
+		}
+		const selfTotal = numberOrZero(response?.total_score);
+		const foundTotal = numberOrZero(research.total_score);
+		gapRows.push({
+			label: "Overall",
+			subtitle: "",
+			self: String(selfTotal),
+			found: String(foundTotal),
+			gap: gapText(selfTotal, foundTotal),
+		});
+	}
+
+	const selfScore = numberOrZero(response?.total_score);
+	const researchScore = numberOrZero(research.total_score);
+	const researchBand = resolveBand(researchScore);
+	let bandSteps = 0;
+	if (response && researchBand) {
+		const selfBand = resolveBand(selfScore);
+		bandSteps = selfBand && researchBand ? Math.abs(bands.indexOf(researchBand) - bands.indexOf(selfBand)) : 0;
+	}
+
+	return {
+		present: true,
+		hasSelfResponse: response != null,
+		personName,
+		preparedFor,
+		identifiedBy: research.linkedin_url,
+		validationStatement: research.validation_note,
+		roleLine: research.role_line ?? "",
+		execSummary: findings.execSummary ?? "",
+		intro: findings.intro ?? "",
+		calloutTitle: findings.calloutTitle ?? "",
+		calloutBody: findings.calloutBody ?? "",
+		groups: (findings.groups ?? []).slice(0, 4).map((group) => ({
+			title: group.title,
+			items: group.items,
+		})),
+		claims: (findings.claims ?? []).slice(0, 3),
+		gapRows,
+		combinedBand: researchBand?.name ?? "",
+		combinedDelta: gapText(selfScore, researchScore),
+		combinedStatement: response
+			? buildCombinedStatement({
+					selfScore,
+					researchScore,
+					bandSteps,
+					researchBandName: researchBand?.name ?? "",
+				})
+			: "",
+		weakestAreas: findings.weakestAreas ?? [],
+		methodRawScores: findings.rawScoresNote ?? "",
+		methodSources: findings.sourceSummary ?? "",
+		researchedAt: isoDay(research.researched_at),
+		reportDate: isoDay(response?.completed_at) || isoDay(research.researched_at),
+	};
+}
+
+/**
+ * Section five merge: person-specific research content wins field-by-field;
+ * an omitted field falls through to the band's copy; the band copy stands
+ * alone when no research exists.
+ */
+export function mergeNextSteps(
+	band: StageBand | null,
+	findings: ResearchFindings,
+): Pick<
+	ReportData,
+	| "strongestAreas"
+	| "priorityActions"
+	| "strategicFocus"
+	| "strengths"
+	| "opportunities"
+	| "twelveMonthTarget"
+	| "roadmap"
+> {
+	return {
+		strongestAreas: findings.strongestAreas ?? band?.strongestAreas ?? [],
+		priorityActions: findings.priorityActions ?? band?.priorityActions ?? [],
+		strategicFocus: findings.strategicFocus ?? band?.strategicFocus ?? "",
+		strengths: findings.strengths ?? band?.strengths ?? [],
+		opportunities: findings.opportunities ?? band?.opportunities ?? [],
+		twelveMonthTarget: findings.twelveMonthTarget ?? band?.twelveMonthTarget ?? "",
+		roadmap:
+			findings.sprintPhases ??
+			(band?.roadmap
+				? Object.keys(band.roadmap)
+						.sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
+						.map((key) => band.roadmap?.[key])
+						.filter((phase): phase is NonNullable<typeof phase> => !!phase)
+				: []),
+	};
+}
+
+/**
+ * Pairing lookup used by the report loader's pair resolver: the identity key
+ * BOTH sides share, computed with the one shared normalisation.
+ */
+export function pairingKeyForResponse(
+	response: Pick<ReportPairResponseInput, "linkedin_url"> | null | undefined,
+): string | null {
+	return normaliseLinkedinIdentity(response?.linkedin_url);
+}

package/src/fn-routers/linkedin-identity.ts

@@ -0,0 +1,36 @@
+/**
+ * @system service-boot
+ * @status handwritten @indivisible-unit owner=lane/unified-authority-index-report reason="one identity normalisation shared by the research writer and the report pairing lookup — a second spelling of the rule is the drift the pairing exists to prevent"
+ * @edit edit directly
+ *
+ * linkedin-identity.ts — the ONE normalisation from a LinkedIn profile URL to
+ * the pairing key that joins research passes to quiz responses.
+ *
+ * WHY IT EXISTS AS A SHARED UNIT (operator pin, 2026-09-04): the same person
+ * arrives as `https://www.linkedin.com/in/annaosherov/` on a quiz response and
+ * as `linkedin.com/in/AnnaOsherov` in a research note. Both sides MUST
+ * collapse to the same `identity_key` or the report renders one half of the
+ * person. The normalisation therefore lives here, exported once, and every
+ * surface that writes or looks up an identity key calls THIS function — a
+ * second local copy of the rule is the drift the pairing exists to prevent.
+ *
+ * Rule: trim; lowercase; strip the scheme (http/https); strip a leading
+ * `www.`; strip one trailing slash. Everything else is kept verbatim, so
+ * `linkedin.com/in/annaosherov` and a custom slug both survive intact.
+ * Non-LinkedIn or empty input returns null — callers refuse rather than pair
+ * on a guessed key.
+ */
+
+export function normaliseLinkedinIdentity(
+	rawUrl: string | null | undefined,
+): string | null {
+	if (typeof rawUrl !== "string") return null;
+	let value = rawUrl.trim().toLowerCase();
+	if (value.length === 0) return null;
+	value = value.replace(/^https?:\/\//, "");
+	value = value.replace(/^www\./, "");
+	value = value.replace(/\/+$/, "");
+	if (value.length === 0) return null;
+	if (!value.includes("linkedin.com")) return null;
+	return value;
+}

package/src/mount-orpc-router.ts

@@ -239,7 +239,6 @@ export async function mountOrpcRouter(
 				// only signal is a fleet-wide spike in 500s with no traceback —
 				// measured 2026-09-04 when the regenerated prisma client shipped
 				// an empty orm and every model action returned a silent 500.
-				// This makes every 500 LOUD with the request path for routing.
 				if (result.response.status >= 500) {
 					log.error(
 						`[ORPC] ${c.req.method} ${c.req.path} → ${result.response.status}`,