@teamscala/service-boot 0.23.401 → 0.23.402

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.401",
+  "version": "0.23.402",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

package/src/fn-routers/public-assessment-router.test.ts

@@ -28,6 +28,7 @@ let capturedEvent: { kind: string; payload: Record<string, unknown> } | null = n
 /** Mutable so one test can stub a brand row with a relative logo path. */
 let brandRowStub: {
 	companyName: string | null;
+	companyFriendlyName?: string | null;
 	primaryColor: string;
 	accentColor: string | null;
 	logo: { light: string | null; dark: string | null; brand: string | null };
@@ -58,7 +59,9 @@ mock.module("@teamscala/api-resend/send-email", () => ({
 // applyTemplateVars stays the REAL implementation — only lookup is stubbed.
 mock.module("@teamscala/email/templates/lookup", () => ({
 	lookupTemplate: async () => ({
-		subject: "Your Authority Index — {{totalScore}}/100 ({{bandLabel}})",
+		// Mirrors the live authority-index-report row, which leads with {{orgName}}
+		// — a stub without it cannot catch a wrong org name in the subject.
+		subject: "{{orgName}}: your Authority Index — {{totalScore}}/100 ({{bandLabel}})",
 		bodyHtml:
 			"{{brandLogoHtml}}<h1>{{totalScore}}/100 — {{bandLabel}}</h1><h2>{{reportTitle}}</h2><p>{{tagline}}</p>{{narrativeHtml}}{{pillarNotesHtml}}{{priorityActionsHtml}}{{roadmapHtml}}{{strategicFocusHtml}}{{opportunitiesHtml}}{{twelveMonthTargetHtml}}",
 		bodyText:
@@ -287,6 +290,46 @@ describe("publicAssessment.submit — email band single-sourced from stage_bands
 		expect(capturedEvent?.payload.band).toBe("experimenting");
 	});
 
+	test("the subject and logo alt use the FRIENDLY name, not the legal entity", async () => {
+		// company_name is the legal entity (GMG APAC); company_friendly_name is
+		// what customers know the org as (launcha). Recipients were getting
+		// "GMG APAC: your Authority Index" and alt="GMG APAC".
+		brandRowStub = {
+			companyName: "GMG APAC",
+			companyFriendlyName: "launcha",
+			primaryColor: "#FF4500",
+			accentColor: null,
+			logo: { light: "/api/assets/5b742740/logos/launcha.png", dark: null, brand: null },
+		};
+		const emailPromise = new Promise<CapturedEmail>((resolve) => {
+			emailResolve = resolve;
+		});
+		await submitWith45(new Headers({ "x-forwarded-host": "quiz.scala.business" }));
+		const email = await emailPromise;
+
+		expect(email.subject).toContain("launcha:");
+		expect(email.subject).not.toContain("GMG APAC");
+		expect(email.html).toContain('alt="launcha"');
+	});
+
+	test("an org with no friendly name still gets its legal name, unchanged", async () => {
+		// The fallback must stay intact: most orgs have never set a friendly name.
+		brandRowStub = {
+			companyName: "GMG APAC",
+			companyFriendlyName: null,
+			primaryColor: "#FF4500",
+			accentColor: null,
+			logo: { light: "/api/assets/5b742740/logos/launcha.png", dark: null, brand: null },
+		};
+		const emailPromise = new Promise<CapturedEmail>((resolve) => {
+			emailResolve = resolve;
+		});
+		await submitWith45(new Headers({ "x-forwarded-host": "quiz.scala.business" }));
+		const email = await emailPromise;
+
+		expect(email.subject).toContain("GMG APAC:");
+	});
+
 	test("a relative brand logo renders as an absolute img src from the serving host", async () => {
 		brandRowStub = {
 			companyName: "GMG APAC",

package/src/fn-routers/public-assessment-router.ts

@@ -151,7 +151,13 @@ async function sendAuthorityReportEmail(opts: {
 	const sender = await resolveEmailSender(opts.organisationId ?? null, {
 		brand: brandRow
 			? {
-					orgName: brandRow.companyName ?? "",
+					// The FRIENDLY name is the customer-facing one; company_name is the
+					// legal entity. Recipients were getting "GMG APAC: your Authority
+					// Index" and alt="GMG APAC" on the logo, for an org whose brand is
+					// Launcha. Same precedence the platform already uses in
+					// agreement-gate (friendly ?? legal), so an org that never set a
+					// friendly name is unchanged.
+					orgName: brandRow.companyFriendlyName || brandRow.companyName || "",
 					primaryColor: brandRow.primaryColor,
 					accentColor: brandRow.accentColor ?? null,
 					logoUrl: absolutizeAssetUrl(brandRow.logo.light),

package/src/handlers/messaging-send-reconcile-logic.test.ts

@@ -0,0 +1,81 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Fixture pair for the outbound-dispatch reconciliation logic: the clean
+ * fixture (every GOWA outbound id already recorded) and the violating fixture
+ * (a raw-dispatched send GOWA knows about that left no messaging_logs row —
+ * the 2026-08-26 measured class — which MUST come back as a backfill
+ * candidate).
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	buildBackfillRow,
+	diffOutboundSends,
+	type GowaOutboundMessage,
+} from "./messaging-send-reconcile-logic.ts";
+
+const NOW = new Date("2026-08-26T02:30:00Z");
+const SETTLE_MS = 120_000;
+
+describe("diffOutboundSends", () => {
+	const rawSend: GowaOutboundMessage = {
+		id: "3EB0F05AC9FAAF24BDA045",
+		chat_jid: "61428193498@s.whatsapp.net",
+		content: "Launcha Authority Index — report page header",
+		timestamp: "2026-08-25T16:13:57Z",
+		is_from_me: true,
+	};
+
+	test("CLEAN: every outbound id already recorded — nothing to backfill", () => {
+		const missing = diffOutboundSends(
+			[rawSend],
+			new Set(["3EB0F05AC9FAAF24BDA045"]),
+			NOW,
+			SETTLE_MS,
+		);
+		expect(missing).toEqual([]);
+	});
+
+	test("VIOLATING: a GOWA-outbound send with no recorded row is a backfill candidate", () => {
+		const missing = diffOutboundSends([rawSend], new Set(), NOW, SETTLE_MS);
+		expect(missing).toHaveLength(1);
+		expect(missing[0]).toEqual({
+			id: "3EB0F05AC9FAAF24BDA045",
+			chatJid: "61428193498@s.whatsapp.net",
+			content: "Launcha Authority Index — report page header",
+			timestamp: "2026-08-25T16:13:57.000Z",
+		});
+	});
+
+	test("inbound messages are never candidates (they record themselves via webhook)", () => {
+		const inbound: GowaOutboundMessage = { ...rawSend, is_from_me: false };
+		expect(diffOutboundSends([inbound], new Set(), NOW, SETTLE_MS)).toEqual([]);
+	});
+
+	test("a send younger than the settle window waits one tick for the recorder", () => {
+		const fresh: GowaOutboundMessage = {
+			...rawSend,
+			timestamp: "2026-08-26T02:29:30Z",
+		};
+		expect(diffOutboundSends([fresh], new Set(), NOW, SETTLE_MS)).toEqual([]);
+	});
+});
+
+describe("buildBackfillRow", () => {
+	test("carries the provider id, the recipient, and the reconciled send_kind", () => {
+		const row = buildBackfillRow({
+			id: "3EB0AF4413C8A5A0694B38",
+			chatJid: "61428193498@s.whatsapp.net",
+			content: "The quiz report email as delivered",
+			timestamp: "2026-08-25T16:14:13Z",
+		});
+		expect(row.direction).toBe("outbound");
+		expect(row.event_type).toBe("sent");
+		expect(row.external_msg_id).toBe("3EB0AF4413C8A5A0694B38");
+		expect(row.external_chat_id).toBe("61428193498@s.whatsapp.net");
+		expect(row.user_phone).toBe("61428193498@s.whatsapp.net");
+		expect(row.payload.send_kind).toBe("gowa-reconcile");
+	});
+});

package/src/handlers/messaging-send-reconcile-logic.ts

@@ -0,0 +1,83 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Pure reconciliation logic for the outbound-dispatch coverage half of
+ * `messaging-send-recording-watch`: diff GOWA's outbound message list against
+ * the recorded provider ids and shape the backfill rows — a send dispatched
+ * outside every recording chokepoint exists only in GOWA's list (2026-08-26).
+ */
+
+/** One outbound message from GOWA `getChatMessages` with is_from_me=true. */
+export interface GowaOutboundMessage {
+	id: string;
+	chat_jid: string;
+	content: string | null;
+	timestamp: string | null;
+	is_from_me: boolean;
+}
+
+/** A GOWA-outbound message with no messaging_logs row — the backfill input. */
+export interface MissingSend {
+	id: string;
+	chatJid: string;
+	content: string | null;
+	timestamp: string;
+}
+
+/**
+ * Diff GOWA's outbound truth against the recorded provider ids. Only
+ * `is_from_me` messages count (the bridge device's own sends — inbound arrives
+ * by webhook and records itself). Messages newer than the settle window are
+ * held back one tick so the dispatch-time recorder's own write can land.
+ */
+export function diffOutboundSends(
+	messages: GowaOutboundMessage[],
+	recordedIds: Set<string>,
+	now: Date,
+	settleMs: number,
+): MissingSend[] {
+	const missing: MissingSend[] = [];
+	for (const message of messages) {
+		if (!message.is_from_me) continue;
+		if (!message.id || recordedIds.has(message.id)) continue;
+		const at = Date.parse(message.timestamp ?? "");
+		if (Number.isNaN(at)) continue;
+		if (at > now.getTime() - settleMs) continue;
+		missing.push({
+			id: message.id,
+			chatJid: message.chat_jid,
+			content: message.content,
+			timestamp: new Date(at).toISOString(),
+		});
+	}
+	return missing;
+}
+
+/** The messaging_logs row that makes a bypassed send reconstructible. */
+export function buildBackfillRow(missing: MissingSend): {
+	id: string;
+	platform: "whatsapp";
+	direction: "outbound";
+	event_type: "sent";
+	external_chat_id: string;
+	user_phone: string;
+	external_msg_id: string;
+	content: string | null;
+	payload: Record<string, unknown>;
+	timestampIso: string;
+} {
+	return {
+		id: crypto.randomUUID(),
+		platform: "whatsapp",
+		direction: "outbound",
+		event_type: "sent",
+		external_chat_id: missing.chatJid,
+		user_phone: missing.chatJid,
+		external_msg_id: missing.id,
+		content: missing.content,
+		payload: { send_kind: "gowa-reconcile" },
+		timestampIso: missing.timestamp,
+	};
+}

package/src/handlers/messaging-send-recording-watch.ts

@@ -30,10 +30,28 @@ import {
 	detectUnrecordedSends,
 	type UnrecordedSendRow,
 } from "./messaging-send-recording-logic.ts";
+import {
+	buildBackfillRow,
+	diffOutboundSends,
+	type GowaOutboundMessage,
+} from "./messaging-send-reconcile-logic.ts";
+import {
+	selectChatsToSweep,
+	type GowaChatSummary,
+} from "./messaging-send-sweep-selection.ts";
+import { getSystemIdentity } from "./whatsapp-liveness.ts";
 
 const DEFAULT_SAMPLE_LIMIT = 5;
 /** Bounds the per-tick read while a break runs for weeks; far above daily volume. */
 const QUERY_ROW_CAP = 1000;
+/** GOWA page size cap (the spec's maximum for both listChats and messages). */
+const GOWA_PAGE_LIMIT = 100;
+/** Upper bound on message pages walked per chat per tick. */
+const MAX_MESSAGE_PAGES_PER_CHAT = 5;
+/** A freshly-dispatched send waits this long before the reconcile sweep may
+ * claim it — the tool-dispatch recorder writes its row at dispatch, and
+ * sweeping sooner would backfill a duplicate of a row about to exist. */
+const RECONCILE_SETTLE_MS = 120_000;
 
 export async function messagingSendRecordingWatch({
 	config,
@@ -69,15 +87,155 @@ export async function messagingSendRecordingWatch({
 		log.info(
 			`[messaging-send-recording-watch] poll complete — every outbound send at/after ${recordedSince} recorded its provider id`,
 		);
-		return;
+	} else {
+		const payload = buildUnrecordedPayload(finding, recordedSince);
+		recordEvent({ kind: "messaging.send.unrecorded", payload });
+		log.warn(
+			`[messaging-send-recording-watch] ${finding.unrecordedCount} outbound send(s) at/after ${recordedSince} recorded no provider message id — their delivery receipts can never correlate`,
+			payload,
+		);
+	}
+
+	// Dispatch-coverage reconcile — the row-shape check above can only inspect
+	// rows that EXIST; a send dispatched to GOWA outside every recording
+	// chokepoint (measured 2026-08-26: raw multipart sends delivered with zero
+	// rows) is invisible to it. GOWA's own message list is the authoritative
+	// outbound record, so this sweep backfills what bypassed us. Failure here
+	// must never take the row-shape check down with it.
+	try {
+		const backfilled = await reconcileOutboundDispatches(recordedSince);
+		if (backfilled > 0) {
+			log.warn(
+				`[messaging-send-recording-watch] reconcile: backfilled ${backfilled} outbound send(s) GOWA delivered with no messaging_logs row (dispatched outside the recording surface)`,
+			);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		log.warn(`[messaging-send-recording-watch] reconcile sweep failed: ${message}`);
+	}
+}
+
+/** Dispatch one api_gowa_chats action through the central /mcp loopback — the
+ * same single sealed-credential surface whatsapp-liveness uses, as the system
+ * caller. */
+async function dispatchGowaChats(
+	action: string,
+	params: Record<string, unknown>,
+): Promise<unknown> {
+	const { forwardToolToCentralMcp } = await import(
+		"@teamscala/chat-completion/central-tool-forwarder"
+	);
+	const { userId, organisationId } = await getSystemIdentity();
+	return forwardToolToCentralMcp(
+		"api_gowa_chats",
+		{ action, params },
+		{ userId, organisationId } as Parameters<typeof forwardToolToCentralMcp>[2],
+	);
+}
+
+interface GowaPaged<T> {
+	results?: { data?: T[]; pagination?: { total?: number } };
+}
+
+/**
+ * The convergent half of the watch: walk GOWA's chats newest-first for
+ * outbound activity at/after the baseline, read each qualifying chat's own
+ * sends, and backfill every provider id messaging_logs is missing. Idempotent
+ * by external_msg_id — a backfilled row can never be backfilled twice, and the
+ * settle window keeps it from racing the dispatch-time recorder.
+ */
+async function reconcileOutboundDispatches(recordedSince: string): Promise<number> {
+	const log = getAppLogger();
+	const horizonMs = Date.parse(recordedSince);
+	if (Number.isNaN(horizonMs)) return 0;
+
+	const chatJids: string[] = [];
+	for (let offset = 0; offset < 100 * 20; offset += GOWA_PAGE_LIMIT) {
+		const page = (await dispatchGowaChats("listChats", {
+			limit: GOWA_PAGE_LIMIT,
+			offset,
+		})) as GowaPaged<GowaChatSummary> | undefined;
+		const chats = (page?.results?.data ?? []) as GowaChatSummary[];
+		if (chats.length === 0) break;
+		const { toSweep, mayStopPaging } = selectChatsToSweep(chats, horizonMs);
+		chatJids.push(...toSweep);
+		if (mayStopPaging) break;
+	}
+
+	const outbound: GowaOutboundMessage[] = [];
+	for (const chatJid of chatJids) {
+		for (let page = 0; page < MAX_MESSAGE_PAGES_PER_CHAT; page++) {
+			const messages = (await dispatchGowaChats("getChatMessages", {
+				chat_jid: chatJid,
+				is_from_me: true,
+				start_time: recordedSince,
+				limit: GOWA_PAGE_LIMIT,
+				offset: page * GOWA_PAGE_LIMIT,
+			})) as GowaPaged<GowaOutboundMessage> | undefined;
+			const batch = ((messages?.results?.data ?? []) as GowaOutboundMessage[]).filter(
+				(m) => m && typeof m.id === "string",
+			);
+			outbound.push(...batch);
+			if (batch.length < GOWA_PAGE_LIMIT) break;
+		}
+	}
+	if (outbound.length === 0) return 0;
+
+	const prisma = getPrisma();
+	const ids = outbound.map((m) => m.id);
+	const recorded = await prisma.$queryRawUnsafe<Array<{ external_msg_id: string }>>(
+		`SELECT external_msg_id FROM messaging_logs WHERE external_msg_id = ANY($1::text[])`,
+		ids,
+	);
+	const recordedIds = new Set(recorded.map((r) => r.external_msg_id));
+	const missing = diffOutboundSends(outbound, recordedIds, new Date(), RECONCILE_SETTLE_MS);
+	if (missing.length === 0) return 0;
+
+	for (const miss of missing) {
+		const row = buildBackfillRow(miss);
+		// createMany + skipDuplicates: the table's unique (agent_id,
+		// external_chat_id, external_msg_id) makes a double-backfill (a sweep
+		// racing the dispatch-time recorder) a no-op instead of a crash.
+		await prisma.messaging_logs.createMany({
+			skipDuplicates: true,
+			data: {
+				id: row.id,
+				organisation_id: "",
+				platform: row.platform,
+				agent_id: "",
+				external_chat_id: row.external_chat_id,
+				user_phone: row.user_phone,
+				external_msg_id: row.external_msg_id,
+				direction: row.direction,
+				event_type: row.event_type,
+				content: row.content,
+				payload: {
+					...row.payload,
+					send_at: row.timestampIso,
+					reconciled_at: new Date().toISOString(),
+				},
+				created_at: new Date(row.timestampIso),
+			},
+		});
 	}
 
-	const payload = buildUnrecordedPayload(finding, recordedSince);
-	recordEvent({ kind: "messaging.send.unrecorded", payload });
-	log.warn(
-		`[messaging-send-recording-watch] ${finding.unrecordedCount} outbound send(s) at/after ${recordedSince} recorded no provider message id — their delivery receipts can never correlate`,
-		payload,
+	recordEvent({
+		kind: "messaging.send.reconciled",
+		payload: {
+			backfilledCount: missing.length,
+			baseline: recordedSince,
+			sample: missing.slice(0, DEFAULT_SAMPLE_LIMIT).map((m) => ({
+				external_msg_id: m.id,
+				chat_id: m.chatJid,
+				content: m.content?.slice(0, 120) ?? null,
+				sent_at: m.timestamp,
+			})),
+		},
+	});
+	log.info(
+		`[messaging-send-recording-watch] reconcile: ${missing.length} unrecorded outbound send(s) backfilled from GOWA truth`,
 	);
+	return missing.length;
 }
 
 pgBossHandlerRegistry.register(

package/src/handlers/messaging-send-sweep-selection.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Tests for the reconcile sweep's chat-page selection.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	selectChatsToSweep,
+	type GowaChatSummary,
+} from "./messaging-send-sweep-selection.ts";
+
+describe("selectChatsToSweep", () => {
+	test("keeps chats at/after the horizon and lets paging stop once a page is older", () => {
+		const chats: GowaChatSummary[] = [
+			{ jid: "a@s.whatsapp.net", last_message_time: "2026-08-26T02:14:00Z" },
+			{ jid: "b@s.whatsapp.net", last_message_time: "2026-08-25T16:14:13Z" },
+			{ jid: "old@s.whatsapp.net", last_message_time: "2026-08-01T00:00:00Z" },
+		];
+		const { toSweep, mayStopPaging } = selectChatsToSweep(
+			chats,
+			Date.parse("2026-08-25T10:19:00Z"),
+		);
+		expect(toSweep).toEqual(["a@s.whatsapp.net", "b@s.whatsapp.net"]);
+		expect(mayStopPaging).toBe(true);
+	});
+
+	test("keeps paging while the page's newest chats still qualify", () => {
+		const chats: GowaChatSummary[] = [
+			{ jid: "a@s.whatsapp.net", last_message_time: "2026-08-26T02:14:00Z" },
+		];
+		const { mayStopPaging } = selectChatsToSweep(chats, Date.parse("2026-08-25T10:19:00Z"));
+		expect(mayStopPaging).toBe(false);
+	});
+
+	test("a chat with no last_message_time never qualifies and stops paging", () => {
+		const { toSweep, mayStopPaging } = selectChatsToSweep(
+			[{ jid: "silent@s.whatsapp.net", last_message_time: null }],
+			0,
+		);
+		expect(toSweep).toEqual([]);
+		expect(mayStopPaging).toBe(true);
+	});
+});

package/src/handlers/messaging-send-sweep-selection.ts

@@ -0,0 +1,35 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Chat-page selection for the messaging-send reconcile sweep: which paged
+ * GOWA chats (newest-first) still have activity at/after the baseline, and
+ * whether paging may stop. Pure and dependency-free, the same shape as the
+ * sibling *-logic units.
+ */
+
+/** One chat from GOWA `listChats` — only the sweep-relevant fields. */
+export interface GowaChatSummary {
+	jid: string;
+	last_message_time: string | null;
+}
+
+/** Chats worth sweeping: those with activity at/after the horizon. */
+export function selectChatsToSweep(
+	chats: GowaChatSummary[],
+	horizonMs: number,
+): { toSweep: string[]; mayStopPaging: boolean } {
+	const toSweep: string[] = [];
+	for (const chat of chats) {
+		const at = Date.parse(chat.last_message_time ?? "");
+		if (!Number.isNaN(at) && at >= horizonMs) toSweep.push(chat.jid);
+	}
+	const last = chats[chats.length - 1];
+	// A null/unparseable last_message_time means the chat never messaged (or
+	// GOWA answered something unexpected) — it cannot hide an outbound send, so
+	// it reads as "older than the horizon" for the paging decision.
+	const lastAt = Date.parse(last?.last_message_time ?? "");
+	const mayStopPaging = chats.length === 0 || Number.isNaN(lastAt) || lastAt < horizonMs;
+	return { toSweep, mayStopPaging };
+}

package/src/handlers/whatsapp-liveness.ts

@@ -47,7 +47,10 @@ interface GowaListDevicesResponse {
 }
 
 let cachedSystemIdentity: { userId: string | undefined; organisationId: string | undefined } | undefined;
-async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
+/** The system-caller identity for platform-action tool dispatches — shared by
+ * the sibling handlers that dispatch GOWA reads through the central /mcp
+ * (messaging-send-recording-watch reconcile sweep). */
+export async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
 	if (cachedSystemIdentity) return cachedSystemIdentity;
 	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
 	cachedSystemIdentity = {