@teamscala/service-boot 0.23.361 → 0.23.363

package/package.json

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

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

@@ -147,6 +147,27 @@ export function formatSpanMinutes(minutes: number): string {
 	return `${hours >= 10 ? Math.round(hours) : Math.round(hours * 10) / 10} h`;
 }
 
+/**
+ * The WhatsApp message id from a GOWA /send/message result. The canonical
+ * shape (from the spec the api-gowa adapter is generated from,
+ * SendResponse = { code, message, results: { message_id, status } }) is
+ * `results.message_id`; the legacy shape returned the bare id string as
+ * `results`. Delivery is only VERIFIED on a real id — `"true"`, a status
+ * string, or an empty body is not a message id and must not be recorded as
+ * delivered.
+ */
+export function extractGowaMessageId(sendResult: unknown): string | null {
+	const results = (sendResult as { results?: unknown } | undefined)?.results;
+	if (typeof results === "string") {
+		return /^[A-Z0-9]{8,}$/i.test(results) ? results : null;
+	}
+	if (results && typeof results === "object") {
+		const id = (results as { message_id?: unknown }).message_id;
+		if (typeof id === "string" && id.length > 0) return id;
+	}
+	return null;
+}
+
 /**
  * The escalation message — escalation-routing's three-field contract adapted
  * to an automated detector: what was OBSERVED (evidence), what it MEANS

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

@@ -12,6 +12,7 @@ import { describe, expect, test } from "bun:test";
 import {
 	composeEscalationMessage,
 	decideSweep,
+	extractGowaMessageId,
 	type EscalationEpisode,
 	type FaultAggregate,
 	type FaultEscalationPolicy,
@@ -166,6 +167,26 @@ describe("decideSweep — resolution + re-arm", () => {
 	});
 });
 
+describe("extractGowaMessageId — delivery verification", () => {
+	test("the canonical GOWA SendResponse shape yields results.message_id", () => {
+		expect(extractGowaMessageId({ code: "SUCCESS", results: { message_id: "3EB089B9D6ADD58153C561", status: "sent" } })).toBe(
+			"3EB089B9D6ADD58153C561",
+		);
+	});
+
+	test("the legacy bare-string results shape yields the id", () => {
+		expect(extractGowaMessageId({ results: "3EB089B9D6ADD58153C561" })).toBe("3EB089B9D6ADD58153C561");
+	});
+
+	test("a 'true' ack is NOT a message id — delivery stays unverified", () => {
+		// A boolean-ish ack string must never be recorded as a delivered id:
+		// that would mark the episode delivered with an unfollowable handle.
+		expect(extractGowaMessageId({ results: "true" })).toBeNull();
+		expect(extractGowaMessageId({ code: "SUCCESS", message: "sent", results: { status: "sent" } })).toBeNull();
+		expect(extractGowaMessageId({ code: "SUCCESS" })).toBeNull();
+	});
+});
+
 describe("composeEscalationMessage", () => {
 	test("carries the three escalation-routing fields and stays phone-sized", () => {
 		const message = composeEscalationMessage({

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

@@ -51,10 +51,12 @@ import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
+import { getServerClient } from "../page-server-orpc/server-client.ts";
 import {
 	composeEscalationDescription,
 	composeEscalationMessage,
 	decideSweep,
+	extractGowaMessageId,
 	type EscalationEpisode,
 	type FaultAggregate,
 	type KindThresholdOverride,
@@ -115,6 +117,42 @@ async function getSystemIdentity(): Promise<{ userId: string | undefined; organi
 	return cachedSystemIdentity;
 }
 
+/**
+ * The system-authed in-process ORPC client (set at boot after the router is
+ * built — no-arg form carries the system super-admin context, correct for a
+ * platform system action). Per `no-direct-prisma-outside-orpc`, every WRITE in
+ * this handler routes through it; the single raw read (the event_log
+ * recurrence aggregate, a GROUP BY no generated CRUD expresses) uses the
+ * assigned-client form with $queryRawUnsafe — the lane-attention-sweep
+ * precedent in this same directory. Timestamps are ISO strings, never Date
+ * instances (the generated valibot schemas require it).
+ */
+function orpc(): OrpcSurface {
+	return getServerClient() as unknown as OrpcSurface;
+}
+
+/** The router subset this handler uses — mirrors the generated procedure args. */
+interface OrpcSurface {
+	platform_fault_escalations: {
+		upsert(args: {
+			where: { kind: string };
+			create: Record<string, unknown>;
+			update: Record<string, unknown>;
+		}): Promise<unknown>;
+		update(args: { where: { kind: string }; data: Record<string, unknown> }): Promise<unknown>;
+		findMany(args?: { where?: Record<string, unknown> }): Promise<Array<Record<string, unknown>>>;
+	};
+	messaging_bots: {
+		findFirst(args: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+	};
+	work_items: {
+		create(args: { data: Record<string, unknown>; select?: Record<string, unknown> }): Promise<{ id: string }>;
+	};
+	comments: {
+		create(args: { data: Record<string, unknown> }): Promise<{ id: string }>;
+	};
+}
+
 async function loadConfig(): Promise<FaultEscalationConfig> {
 	return loadRegistryConfig("config", CONFIG_SLUG, FaultEscalationConfigSchema);
 }
@@ -149,15 +187,14 @@ async function fetchAggregates(patterns: string[], windowMinutes: number): Promi
 }
 
 async function resolveOperatorRelay(): Promise<OperatorRelayBot> {
-	const prisma = getPrisma();
-	const bot = await prisma.messaging_bots.findFirst({
+	const bot = (await orpc().messaging_bots.findFirst({
 		where: {
 			is_active: true,
 			platform: "whatsapp",
 			flow_config: { path: ["mode"], equals: "operator-relay" },
 		},
 		select: { id: true, organisation_id: true, external_id: true, flow_config: true },
-	});
+	})) as unknown as OperatorRelayBot | null;
 	if (!bot) throw new Error("platform-fault-escalation: no active operator-relay WhatsApp bot row");
 	const phone = (bot.flow_config as { operator_phone?: string } | null)?.operator_phone;
 	if (!phone) throw new Error("platform-fault-escalation: operator-relay bot has no operator_phone");
@@ -178,39 +215,27 @@ async function resolvePaDeviceId(paPhoneDigits: string): Promise<string | undefi
 	return match?.id;
 }
 
-function extractMessageId(sendResult: unknown): string | null {
-	const results = (sendResult as { results?: unknown } | undefined)?.results;
-	const id =
-		typeof results === "string"
-			? results
-			: Array.isArray(results)
-				? ((results[0] as { id?: unknown } | undefined)?.id as string | undefined)
-				: ((results as { id?: unknown } | undefined)?.id as string | undefined);
-	return typeof id === "string" && id.length > 0 ? id : null;
-}
-
 async function deliverEscalation(
 	kind: string,
 	aggregate: FaultAggregate,
 	config: FaultEscalationConfig,
 ): Promise<{ messageId: string; workItemId: string }> {
 	const log = getAppLogger();
-	const prisma = getPrisma();
 	const now = new Date();
 
 	// 1. Claim the episode BEFORE sending, so a send failure leaves a durable
 	// claim the next sweep retries instead of a lost escalation.
-	await prisma.platform_fault_escalations.upsert({
+	await orpc().platform_fault_escalations.upsert({
 		where: { kind },
 		create: {
 			kind,
-			first_seen_at: aggregate.firstSeen,
-			last_seen_at: aggregate.lastSeen,
+			first_seen_at: aggregate.firstSeen.toISOString(),
+			last_seen_at: aggregate.lastSeen.toISOString(),
 			event_count: aggregate.count,
 		},
 		update: {
-			first_seen_at: aggregate.firstSeen,
-			last_seen_at: aggregate.lastSeen,
+			first_seen_at: aggregate.firstSeen.toISOString(),
+			last_seen_at: aggregate.lastSeen.toISOString(),
 			event_count: aggregate.count,
 			resolved_at: null,
 		},
@@ -246,7 +271,7 @@ async function deliverEscalation(
 
 	// 3. VERIFY delivery before recording it: the send must return a WhatsApp
 	// message id. No id => throw, the claim stays undelivered, next sweep retries.
-	const messageId = extractMessageId(sendResult);
+	const messageId = extractGowaMessageId(sendResult);
 	if (!messageId) {
 		throw new Error(
 			`platform-fault-escalation: WhatsApp send for '${kind}' returned no message id — not recording delivery`,
@@ -254,7 +279,7 @@ async function deliverEscalation(
 	}
 
 	// 4. Durable record: the work_items task the PA reads back / the operator answers on.
-	const workItem = await prisma.work_items.create({
+	const workItem = await orpc().work_items.create({
 		data: {
 			kind: "task",
 			parent_id: config.parent_project_id,
@@ -276,14 +301,14 @@ async function deliverEscalation(
 	});
 
 	// 5. Readback-correct the episode: delivered + linked in one update.
-	await prisma.platform_fault_escalations.update({
+	await orpc().platform_fault_escalations.update({
 		where: { kind },
 		data: {
-			escalated_at: now,
+			escalated_at: now.toISOString(),
 			work_item_id: workItem.id,
 			delivered_message_id: messageId,
-			last_updated_at: now,
-			updated_at: now,
+			last_updated_at: now.toISOString(),
+			updated_at: now.toISOString(),
 		},
 	});
 
@@ -300,19 +325,18 @@ async function deliverEscalation(
 }
 
 async function updateEpisode(aggregate: FaultAggregate, episode: EscalationEpisode): Promise<void> {
-	const prisma = getPrisma();
 	const now = new Date();
-	await prisma.platform_fault_escalations.update({
+	await orpc().platform_fault_escalations.update({
 		where: { kind: episode.kind },
 		data: {
-			last_seen_at: aggregate.lastSeen,
+			last_seen_at: aggregate.lastSeen.toISOString(),
 			event_count: aggregate.count,
-			last_updated_at: now,
-			updated_at: now,
+			last_updated_at: now.toISOString(),
+			updated_at: now.toISOString(),
 		},
 	});
 	if (episode.workItemId) {
-		await prisma.comments.create({
+		await orpc().comments.create({
 			data: {
 				work_item_id: episode.workItemId,
 				content: `Still recurring: ${aggregate.count} events, last at ${aggregate.lastSeen.toISOString()}. No new escalation (already escalated and unresolved).`,
@@ -328,14 +352,13 @@ async function updateEpisode(aggregate: FaultAggregate, episode: EscalationEpiso
 }
 
 async function resolveEpisode(episode: EscalationEpisode, quietMinutes: number): Promise<void> {
-	const prisma = getPrisma();
 	const now = new Date();
-	await prisma.platform_fault_escalations.update({
+	await orpc().platform_fault_escalations.update({
 		where: { kind: episode.kind },
-		data: { resolved_at: now, updated_at: now },
+		data: { resolved_at: now.toISOString(), updated_at: now.toISOString() },
 	});
 	if (episode.workItemId) {
-		await prisma.comments.create({
+		await orpc().comments.create({
 			data: {
 				work_item_id: episode.workItemId,
 				content: `Fault stopped — no '${episode.kind}' events for ${Math.round(quietMinutes)} min. Episode closed; the fault will re-escalate if it recurs.`,
@@ -359,9 +382,18 @@ async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig })
 	// 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 getPrisma().platform_fault_escalations.findMany({
+	const openEpisodes = (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;
+		last_updated_at: string | Date | null;
+	}>;
 	const episodes: EscalationEpisode[] = openEpisodes.map((row) => ({
 		kind: row.kind,
 		firstSeenAt: new Date(row.first_seen_at),