@teamscala/service-boot 0.23.418 → 0.23.419

package/package.json

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

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

@@ -0,0 +1,54 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The config row of the platform-fault-escalation pg-boss handler
+ * (config/platform-fault-escalation).
+ *
+ * Split out of handlers/platform-fault-escalation.ts (500 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+export const CONFIG_SLUG = "platform-fault-escalation";
+
+export const FaultEscalationConfigSchema = v.object({
+	/** Postgres regex patterns selecting watched event_log kinds. */
+	watched_kind_patterns: v.array(v.string()),
+	/** Lookback window for the recurrence/duration aggregate, minutes. */
+	window_minutes: v.number(),
+	min_count: v.number(),
+	min_span_minutes: v.number(),
+	/** Per-kind recurrence/duration overrides — low-rate-but-persistent kinds. */
+	kind_thresholds: v.optional(
+		v.record(
+			v.string(),
+			v.object({
+				min_count: v.optional(v.number()),
+				min_span_minutes: v.optional(v.number()),
+			}),
+		),
+	),
+	resolve_after_minutes: v.number(),
+	/** The orchestrator's work item — escalations are COMMENTS on it, never
+	 * task rows (the fleet-task-placement CHECK constraint refuses a system
+	 * task without session identity, and an escalation is a finding, not an
+	 * assigned unit of work). */
+	orchestrator_work_item_id: v.string(),
+	/** Per-kind copy for the message (impact + recommendation). Falls back to default_copy. */
+	copy: v.record(v.string(), v.object({ impact: v.string(), recommendation: v.string() })),
+	default_copy: v.object({ impact: v.string(), recommendation: v.string() }),
+	/** Per-kind payload-field whitelist sampled into the message's evidence
+	 * line — named fields ONLY, never the whole payload: some kinds embed
+	 * request context, and the escalation channel is WhatsApp. */
+	sample_fields: v.optional(v.record(v.string(), v.array(v.string()))),
+});
+
+export type FaultEscalationConfig = v.InferOutput<typeof FaultEscalationConfigSchema>;
+
+export function loadFaultEscalationConfig(): Promise<FaultEscalationConfig> {
+	return loadRegistryConfig("config", CONFIG_SLUG, FaultEscalationConfigSchema);
+}

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

@@ -0,0 +1,173 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Escalation delivery of the platform-fault-escalation handler: claim the
+ * episode, resolve the operator-relay WhatsApp bot, send via
+ * messaging_whatsapp_send, verify the message id, record the comment +
+ * readback-corrected episode — and close a quiet episode.
+ *
+ * Split out of handlers/platform-fault-escalation.ts (500 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import type { ExecutionContext } from "@teamscala/os/contracts/mcp";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import {
+	composeEscalationMessage,
+	extractWhatsAppMessageId,
+	type EscalationEpisode,
+	type FaultAggregate,
+} from "../platform-fault-escalation-logic.ts";
+import type { FaultEscalationConfig } from "./config.ts";
+import { fetchLatestEvidence } from "./event-log-queries.ts";
+import { getSystemIdentity, orpc } from "./orpc-client.ts";
+
+interface OperatorRelayBot {
+	id: string;
+	organisation_id: string;
+	external_id: string | null;
+	flow_config: { operator_phone?: string } | null;
+}
+
+async function resolveOperatorRelay(): Promise<OperatorRelayBot> {
+	const bot = (await (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");
+	return bot as OperatorRelayBot;
+}
+
+export async function deliverEscalation(
+	kind: string,
+	aggregate: FaultAggregate,
+	config: FaultEscalationConfig,
+): Promise<{ messageId: string; workItemId: string }> {
+	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 (await orpc()).platform_fault_escalations.upsert({
+		where: { kind },
+		create: {
+			kind,
+			first_seen_at: aggregate.firstSeen.toISOString(),
+			last_seen_at: aggregate.lastSeen.toISOString(),
+			event_count: aggregate.count,
+		},
+		update: {
+			first_seen_at: aggregate.firstSeen.toISOString(),
+			last_seen_at: aggregate.lastSeen.toISOString(),
+			event_count: aggregate.count,
+			resolved_at: null,
+		},
+	});
+
+	// 2. Resolve the operator relay and send. The send surface is the
+	// `messaging_whatsapp_send` intrinsic (scala-mcp / messaging-mcp-boot),
+	// which delegates to the Rust scala-messaging-service — the channel owner
+	// that picks the device and records the send in messaging_logs. The retired
+	// api_gowa_message tool (deactivated 2026-08-26) is no longer callable;
+	// naming it here left every escalation send failing with "Unknown tool".
+	const bot = await resolveOperatorRelay();
+	const operatorPhone = (bot.flow_config as { operator_phone?: string }).operator_phone!;
+	const copy = config.copy[kind] ?? config.default_copy;
+	const { sample, lastEvent } = await fetchLatestEvidence(kind, config.sample_fields?.[kind] ?? []);
+	const message = composeEscalationMessage({
+		kind,
+		aggregate,
+		sample,
+		lastEvent,
+		impact: copy.impact,
+		recommendation: copy.recommendation,
+	});
+
+	const { userId, organisationId } = await getSystemIdentity();
+	const systemCtx: ExecutionContext = { userId, organisationId } as ExecutionContext;
+	const { forwardToolToCentralMcp } = await import("@teamscala/chat-completion/central-tool-forwarder");
+	const sendResult = await forwardToolToCentralMcp(
+		"messaging_whatsapp_send",
+		{ phone: operatorPhone, message },
+		systemCtx,
+	);
+
+	// 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 = extractWhatsAppMessageId(sendResult);
+	if (!messageId) {
+		throw new Error(
+			`platform-fault-escalation: WhatsApp send for '${kind}' returned no message id — not recording delivery. ` +
+				`Response: ${JSON.stringify(sendResult).slice(0, 400)}`,
+		);
+	}
+
+	// 4. Durable record: a COMMENT on the orchestrator's work item — an
+	// escalation is a finding the orchestrator/operator triages, not an
+	// assigned task (the fleet-task-placement constraint refuses task rows
+	// without session identity by design).
+	const comment = await (await orpc()).comments.create({
+		data: {
+			work_item_id: config.orchestrator_work_item_id,
+			content: message,
+			source_cli_session_id: null,
+		},
+	});
+
+	// 5. Readback-correct the episode: delivered + linked in one update.
+	await (await orpc()).platform_fault_escalations.update({
+		where: { kind },
+		data: {
+			escalated_at: now.toISOString(),
+			work_item_id: config.orchestrator_work_item_id,
+			delivered_comment_id: comment.id,
+			delivered_message_id: messageId,
+			last_updated_at: now.toISOString(),
+			updated_at: now.toISOString(),
+		},
+	});
+
+	recordEvent({
+		kind: "platform.fault.escalated",
+		payload: {
+			event_kind: kind,
+			count: aggregate.count,
+			sample,
+			last_event_id: lastEvent?.eventId ?? null,
+			last_event_occurred_at: lastEvent?.occurredAt ?? null,
+			work_item_id: config.orchestrator_work_item_id,
+			delivered_comment_id: comment.id,
+			delivered_message_id: messageId,
+		},
+	});
+	return { messageId, workItemId: config.orchestrator_work_item_id };
+}
+
+export async function resolveEpisode(episode: EscalationEpisode, quietMinutes: number): Promise<void> {
+	const now = new Date();
+	await (await orpc()).platform_fault_escalations.update({
+		where: { kind: episode.kind },
+		data: { resolved_at: now.toISOString(), updated_at: now.toISOString() },
+	});
+	if (episode.workItemId) {
+		await (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.`,
+				sender_role: "system",
+				sender_name: "platform-fault-escalation",
+			},
+		});
+	}
+	recordEvent({
+		kind: "platform.fault.resolved",
+		payload: { event_kind: episode.kind, quiet_minutes: Math.round(quietMinutes), work_item_id: episode.workItemId },
+	});
+}

package/src/handlers/platform-fault-escalation/event-log-queries.ts

@@ -0,0 +1,122 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The bounded event_log reads of the platform-fault-escalation handler: the
+ * recurrence/duration aggregate and the latest-payload evidence sample, both
+ * with the `occurred_at <= now()` database-clock top edge.
+ *
+ * Split out of handlers/platform-fault-escalation.ts (500 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import { getPrisma } from "@teamscala/db/prisma-registry";
+import { formatEscalationSample, type FaultAggregate } from "../platform-fault-escalation-logic.ts";
+import { CONFIG_SLUG } from "./config.ts";
+
+interface EventLogAggregateRow {
+	kind: string;
+	n: bigint;
+	first_seen: Date;
+	last_seen: Date;
+}
+
+export async function fetchAggregates(patterns: string[], windowMinutes: number): Promise<FaultAggregate[]> {
+	const prisma = getPrisma();
+	// Patterns come from the valibot-validated registry row and are regex-only
+	// by construction below; embedding them as one alternation keeps the query
+	// parameter-free on the pattern side while the window is a real parameter.
+	// The window is bounded on BOTH sides by the database's own statement
+	// clock: `occurred_at` is producer-claimed, and an unbounded top edge
+	// admits rows stamped in the future by a skewed or mocked producer clock —
+	// which then fabricate "still recurring" for a quiet fault (measured
+	// 2026-08-26). A future row is not evidence of anything happening now.
+	const regexClass = /^[A-Za-z0-9_\\^$.*+?()[\]{}|-]+$/;
+	for (const pattern of patterns) {
+		if (!regexClass.test(pattern)) {
+			throw new Error(`config/${CONFIG_SLUG}: watched_kind_pattern is not regex-only: ${pattern}`);
+		}
+	}
+	const combined = `(${patterns.join("|")})`;
+	const rows = await prisma.$queryRawUnsafe<EventLogAggregateRow[]>(
+		`SELECT kind, count(*)::bigint AS n, min(occurred_at) AS first_seen, max(occurred_at) AS last_seen
+			 FROM event_log
+			 WHERE occurred_at > now() - ($1::int * interval '1 minute')
+			   AND occurred_at <= now()
+			   AND kind ~ $2::text
+			 GROUP BY kind`,
+		windowMinutes,
+		combined,
+	);
+	return rows.map((row) => ({
+		kind: row.kind,
+		count: Number(row.n),
+		firstSeen: new Date(row.first_seen),
+		lastSeen: new Date(row.last_seen),
+	}));
+}
+
+/**
+ * The message's evidence: the whitelisted sample fields AND the row identity
+ * (id + occurred_at) of the newest payload for the kind. Field names come
+ * from the valibot-validated config row and are constrained to bare
+ * identifiers below, so the JSON path cannot break out of the string. The
+ * `occurred_at <= now()` bound matches the aggregate's top edge: the cited
+ * "last" row must be a real, non-future event whose id rides in the message
+ * so the claim resolves against event_log.
+ */
+export async function fetchLatestEvidence(
+	kind: string,
+	fields: string[],
+): Promise<{ sample: string; lastEvent: { occurredAt: string; eventId: string } | null }> {
+	const prisma = getPrisma();
+	if (fields.length === 0) {
+		const rows = await prisma.$queryRawUnsafe<Array<{ id: unknown; occurred_at: Date }>>(
+			`SELECT id::text, occurred_at
+				 FROM event_log
+				 WHERE kind = $1::text AND occurred_at <= now()
+				 ORDER BY occurred_at DESC
+				 LIMIT 1`,
+			kind,
+		);
+		const top = rows[0];
+		return { sample: "", lastEvent: top ? { occurredAt: isoSeconds(top.occurred_at), eventId: String(top.id) } : null };
+	}
+	for (const field of fields) {
+		if (!/^[A-Za-z0-9_]+$/.test(field)) {
+			throw new Error(`config/${CONFIG_SLUG}: sample_fields entry is not a bare field name: ${field}`);
+		}
+	}
+	const selection = fields.map((field) => `payload_json->'${field}' AS "${field}"`).join(", ");
+	const rows = await prisma.$queryRawUnsafe<Array<Record<string, unknown>>>(
+		`SELECT id::text, occurred_at, ${selection}
+				 FROM event_log
+				 WHERE kind = $1::text AND occurred_at <= now()
+				 ORDER BY occurred_at DESC
+				 LIMIT 1`,
+		kind,
+	);
+	const row = rows[0];
+	if (!row) return { sample: "", lastEvent: null };
+	const parts: string[] = [];
+	for (const field of fields) {
+		const value = row[field];
+		if (value === null || value === undefined) continue;
+		const formatted = formatEscalationSample(value);
+		if (formatted) parts.push(`${field}=${formatted}`);
+	}
+	return {
+		sample: parts.join("; "),
+		lastEvent: {
+			occurredAt: isoSeconds(row.occurred_at as string | Date),
+			eventId: String(row.id),
+		},
+	};
+}
+
+/** ISO-8601 to whole seconds — the same precision event_log stores, so the
+ * cited string round-trips a `WHERE occurred_at = '<cited>'` query. */
+function isoSeconds(value: Date | string): string {
+	return new Date(value).toISOString().replace(/\.\d{3}Z$/, "Z");
+}

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

@@ -0,0 +1,97 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The system-authed in-process ORPC client of the platform-fault-escalation
+ * handler (lazy, built from the composed appRouter) and the system identity
+ * it falls back to.
+ *
+ * Split out of handlers/platform-fault-escalation.ts (500 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+let cachedSystemIdentity: { userId: string | undefined; organisationId: string | undefined } | undefined;
+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 = {
+		userId: row?.system_user_id as string | undefined,
+		organisationId: row?.system_org_id as string | undefined,
+	};
+	return cachedSystemIdentity;
+}
+
+/**
+ * The system-authed in-process ORPC client, built LAZILY on first use from the
+ * SAME composed appRouter the /api/rpc mount uses (getAppRouter — never a raw
+ * re-import of the generated routers, per register-page-server-client's
+ * documented module-identity trap). Built here rather than read from
+ * page-server-orpc/server-client because a pg-boss handler can fire on a
+ * BACKEND service, where the page-server client is never registered — the
+ * empty-router fallback returns a client with no model namespaces (the
+ * TypeError this replaced). Per `no-direct-prisma-outside-orpc`, every WRITE
+ * in this handler routes through this client; the two raw reads (the
+ * event_log recurrence aggregate and the latest-payload sample, shapes no
+ * generated CRUD expresses) use
+ * the assigned-client form with $queryRawUnsafe. Timestamps are ISO strings,
+ * never Date instances (the generated valibot schemas require it).
+ */
+let cachedOrpc: OrpcSurface | null = null;
+export async function orpc(): Promise<OrpcSurface> {
+	if (cachedOrpc) return cachedOrpc;
+	const { createRouterClient } = await import("@orpc/server");
+	const { getAppRouter } = await import("@teamscala/orpc/app-router");
+	const appRouter = (await getAppRouter()) as Record<string, unknown> | null;
+	if (!appRouter) {
+		throw new Error(
+			"platform-fault-escalation: no ORPC appRouter — the service has no generated routers to write through",
+		);
+	}
+	const prismaRegistry = await import("@teamscala/db/prisma-registry");
+	const registryLoader = await import("@teamscala/db/registry/load-config");
+	const { PlatformIdentitySchema } = await import(
+		"@teamscala/db-validation/registry-schemas/platform-identity"
+	);
+	const platformIdentity = await registryLoader.loadRegistryConfig(
+		"config",
+		"platform-identity",
+		PlatformIdentitySchema,
+	);
+	cachedOrpc = createRouterClient(
+		{ ...appRouter } as never,
+		{
+			context: {
+				prisma: prismaRegistry.getPrisma(),
+				user: {
+					id: "system",
+					isSuperAdmin: true,
+					organisationId: platformIdentity.platformOrganisationId,
+				},
+			},
+		} as never,
+	) as unknown as OrpcSurface;
+	return cachedOrpc;
+}
+
+/** The router subset this handler uses — mirrors the generated procedure args. */
+export 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>;
+	};
+	comments: {
+		create(args: { data: Record<string, unknown> }): Promise<{ id: string }>;
+	};
+}

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

@@ -1,411 +1,39 @@
 /**
  * @system server-boot
- * @status handwritten @indivisible-unit
+ * @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 { ExecutionContext } from "@teamscala/os/contracts/mcp";
 import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import * as v from "valibot";
-import { getPrisma } from "@teamscala/db/prisma-registry";
-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 {
-	composeEscalationMessage,
 	decideSweep,
-	extractWhatsAppMessageId,
-	formatEscalationSample,
 	type EscalationEpisode,
-	type FaultAggregate,
 	type KindThresholdOverride,
 } from "./platform-fault-escalation-logic.ts";
-
-const CONFIG_SLUG = "platform-fault-escalation";
-
-const FaultEscalationConfigSchema = v.object({
-	/** Postgres regex patterns selecting watched event_log kinds. */
-	watched_kind_patterns: v.array(v.string()),
-	/** Lookback window for the recurrence/duration aggregate, minutes. */
-	window_minutes: v.number(),
-	min_count: v.number(),
-	min_span_minutes: v.number(),
-	/** Per-kind recurrence/duration overrides — low-rate-but-persistent kinds. */
-	kind_thresholds: v.optional(
-		v.record(
-			v.string(),
-			v.object({
-				min_count: v.optional(v.number()),
-				min_span_minutes: v.optional(v.number()),
-			}),
-		),
-	),
-	resolve_after_minutes: v.number(),
-	/** The orchestrator's work item — escalations are COMMENTS on it, never
-	 * task rows (the fleet-task-placement CHECK constraint refuses a system
-	 * task without session identity, and an escalation is a finding, not an
-	 * assigned unit of work). */
-	orchestrator_work_item_id: v.string(),
-	/** Per-kind copy for the message (impact + recommendation). Falls back to default_copy. */
-	copy: v.record(v.string(), v.object({ impact: v.string(), recommendation: v.string() })),
-	default_copy: v.object({ impact: v.string(), recommendation: v.string() }),
-	/** Per-kind payload-field whitelist sampled into the message's evidence
-	 * line — named fields ONLY, never the whole payload: some kinds embed
-	 * request context, and the escalation channel is WhatsApp. */
-	sample_fields: v.optional(v.record(v.string(), v.array(v.string()))),
-});
-
-type FaultEscalationConfig = v.InferOutput<typeof FaultEscalationConfigSchema>;
-
-interface EventLogAggregateRow {
-	kind: string;
-	n: bigint;
-	first_seen: Date;
-	last_seen: Date;
-}
-
-interface OperatorRelayBot {
-	id: string;
-	organisation_id: string;
-	external_id: string | null;
-	flow_config: { operator_phone?: string } | null;
-}
-
-let cachedSystemIdentity: { userId: string | undefined; organisationId: string | undefined } | undefined;
-async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
-	if (cachedSystemIdentity) return cachedSystemIdentity;
-	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
-	cachedSystemIdentity = {
-		userId: row?.system_user_id as string | undefined,
-		organisationId: row?.system_org_id as string | undefined,
-	};
-	return cachedSystemIdentity;
-}
-
-/**
- * The system-authed in-process ORPC client, built LAZILY on first use from the
- * SAME composed appRouter the /api/rpc mount uses (getAppRouter — never a raw
- * re-import of the generated routers, per register-page-server-client's
- * documented module-identity trap). Built here rather than read from
- * page-server-orpc/server-client because a pg-boss handler can fire on a
- * BACKEND service, where the page-server client is never registered — the
- * empty-router fallback returns a client with no model namespaces (the
- * TypeError this replaced). Per `no-direct-prisma-outside-orpc`, every WRITE
- * in this handler routes through this client; the two raw reads (the
- * event_log recurrence aggregate and the latest-payload sample, shapes no
- * generated CRUD expresses) use
- * the assigned-client form with $queryRawUnsafe. Timestamps are ISO strings,
- * never Date instances (the generated valibot schemas require it).
- */
-let cachedOrpc: OrpcSurface | null = null;
-async function orpc(): Promise<OrpcSurface> {
-	if (cachedOrpc) return cachedOrpc;
-	const { createRouterClient } = await import("@orpc/server");
-	const { getAppRouter } = await import("@teamscala/orpc/app-router");
-	const appRouter = (await getAppRouter()) as Record<string, unknown> | null;
-	if (!appRouter) {
-		throw new Error(
-			"platform-fault-escalation: no ORPC appRouter — the service has no generated routers to write through",
-		);
-	}
-	const prismaRegistry = await import("@teamscala/db/prisma-registry");
-	const registryLoader = await import("@teamscala/db/registry/load-config");
-	const { PlatformIdentitySchema } = await import(
-		"@teamscala/db-validation/registry-schemas/platform-identity"
-	);
-	const platformIdentity = await registryLoader.loadRegistryConfig(
-		"config",
-		"platform-identity",
-		PlatformIdentitySchema,
-	);
-	cachedOrpc = createRouterClient(
-		{ ...appRouter } as never,
-		{
-			context: {
-				prisma: prismaRegistry.getPrisma(),
-				user: {
-					id: "system",
-					isSuperAdmin: true,
-					organisationId: platformIdentity.platformOrganisationId,
-				},
-			},
-		} as never,
-	) as unknown as OrpcSurface;
-	return cachedOrpc;
-}
-
-/** 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>;
-	};
-	comments: {
-		create(args: { data: Record<string, unknown> }): Promise<{ id: string }>;
-	};
-}
-
-async function loadConfig(): Promise<FaultEscalationConfig> {
-	return loadRegistryConfig("config", CONFIG_SLUG, FaultEscalationConfigSchema);
-}
-
-async function fetchAggregates(patterns: string[], windowMinutes: number): Promise<FaultAggregate[]> {
-	const prisma = getPrisma();
-	// Patterns come from the valibot-validated registry row and are regex-only
-	// by construction below; embedding them as one alternation keeps the query
-	// parameter-free on the pattern side while the window is a real parameter.
-	// The window is bounded on BOTH sides by the database's own statement
-	// clock: `occurred_at` is producer-claimed, and an unbounded top edge
-	// admits rows stamped in the future by a skewed or mocked producer clock —
-	// which then fabricate "still recurring" for a quiet fault (measured
-	// 2026-08-26). A future row is not evidence of anything happening now.
-	const regexClass = /^[A-Za-z0-9_\\^$.*+?()[\]{}|-]+$/;
-	for (const pattern of patterns) {
-		if (!regexClass.test(pattern)) {
-			throw new Error(`config/${CONFIG_SLUG}: watched_kind_pattern is not regex-only: ${pattern}`);
-		}
-	}
-	const combined = `(${patterns.join("|")})`;
-	const rows = await prisma.$queryRawUnsafe<EventLogAggregateRow[]>(
-		`SELECT kind, count(*)::bigint AS n, min(occurred_at) AS first_seen, max(occurred_at) AS last_seen
-			 FROM event_log
-			 WHERE occurred_at > now() - ($1::int * interval '1 minute')
-			   AND occurred_at <= now()
-			   AND kind ~ $2::text
-			 GROUP BY kind`,
-		windowMinutes,
-		combined,
-	);
-	return rows.map((row) => ({
-		kind: row.kind,
-		count: Number(row.n),
-		firstSeen: new Date(row.first_seen),
-		lastSeen: new Date(row.last_seen),
-	}));
-}
-
-/**
- * The message's evidence: the whitelisted sample fields AND the row identity
- * (id + occurred_at) of the newest payload for the kind. Field names come
- * from the valibot-validated config row and are constrained to bare
- * identifiers below, so the JSON path cannot break out of the string. The
- * `occurred_at <= now()` bound matches the aggregate's top edge: the cited
- * "last" row must be a real, non-future event whose id rides in the message
- * so the claim resolves against event_log.
- */
-async function fetchLatestEvidence(
-	kind: string,
-	fields: string[],
-): Promise<{ sample: string; lastEvent: { occurredAt: string; eventId: string } | null }> {
-	const prisma = getPrisma();
-	if (fields.length === 0) {
-		const rows = await prisma.$queryRawUnsafe<Array<{ id: unknown; occurred_at: Date }>>(
-			`SELECT id::text, occurred_at
-				 FROM event_log
-				 WHERE kind = $1::text AND occurred_at <= now()
-				 ORDER BY occurred_at DESC
-				 LIMIT 1`,
-			kind,
-		);
-		const top = rows[0];
-		return { sample: "", lastEvent: top ? { occurredAt: isoSeconds(top.occurred_at), eventId: String(top.id) } : null };
-	}
-	for (const field of fields) {
-		if (!/^[A-Za-z0-9_]+$/.test(field)) {
-			throw new Error(`config/${CONFIG_SLUG}: sample_fields entry is not a bare field name: ${field}`);
-		}
-	}
-	const selection = fields.map((field) => `payload_json->'${field}' AS "${field}"`).join(", ");
-	const rows = await prisma.$queryRawUnsafe<Array<Record<string, unknown>>>(
-		`SELECT id::text, occurred_at, ${selection}
-				 FROM event_log
-				 WHERE kind = $1::text AND occurred_at <= now()
-				 ORDER BY occurred_at DESC
-				 LIMIT 1`,
-		kind,
-	);
-	const row = rows[0];
-	if (!row) return { sample: "", lastEvent: null };
-	const parts: string[] = [];
-	for (const field of fields) {
-		const value = row[field];
-		if (value === null || value === undefined) continue;
-		const formatted = formatEscalationSample(value);
-		if (formatted) parts.push(`${field}=${formatted}`);
-	}
-	return {
-		sample: parts.join("; "),
-		lastEvent: {
-			occurredAt: isoSeconds(row.occurred_at as string | Date),
-			eventId: String(row.id),
-		},
-	};
-}
-
-/** ISO-8601 to whole seconds — the same precision event_log stores, so the
- * cited string round-trips a `WHERE occurred_at = '<cited>'` query. */
-function isoSeconds(value: Date | string): string {
-	return new Date(value).toISOString().replace(/\.\d{3}Z$/, "Z");
-}
-
-async function resolveOperatorRelay(): Promise<OperatorRelayBot> {
-	const bot = (await (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");
-	return bot as OperatorRelayBot;
-}
-
-async function deliverEscalation(
-	kind: string,
-	aggregate: FaultAggregate,
-	config: FaultEscalationConfig,
-): Promise<{ messageId: string; workItemId: string }> {
-	const log = getAppLogger();
-	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 (await orpc()).platform_fault_escalations.upsert({
-		where: { kind },
-		create: {
-			kind,
-			first_seen_at: aggregate.firstSeen.toISOString(),
-			last_seen_at: aggregate.lastSeen.toISOString(),
-			event_count: aggregate.count,
-		},
-		update: {
-			first_seen_at: aggregate.firstSeen.toISOString(),
-			last_seen_at: aggregate.lastSeen.toISOString(),
-			event_count: aggregate.count,
-			resolved_at: null,
-		},
-	});
-
-	// 2. Resolve the operator relay and send. The send surface is the
-	// `messaging_whatsapp_send` intrinsic (scala-mcp / messaging-mcp-boot),
-	// which delegates to the Rust scala-messaging-service — the channel owner
-	// that picks the device and records the send in messaging_logs. The retired
-	// api_gowa_message tool (deactivated 2026-08-26) is no longer callable;
-	// naming it here left every escalation send failing with "Unknown tool".
-	const bot = await resolveOperatorRelay();
-	const operatorPhone = (bot.flow_config as { operator_phone?: string }).operator_phone!;
-	const copy = config.copy[kind] ?? config.default_copy;
-	const { sample, lastEvent } = await fetchLatestEvidence(kind, config.sample_fields?.[kind] ?? []);
-	const message = composeEscalationMessage({
-		kind,
-		aggregate,
-		sample,
-		lastEvent,
-		impact: copy.impact,
-		recommendation: copy.recommendation,
-	});
-
-	const { userId, organisationId } = await getSystemIdentity();
-	const systemCtx: ExecutionContext = { userId, organisationId } as ExecutionContext;
-	const { forwardToolToCentralMcp } = await import("@teamscala/chat-completion/central-tool-forwarder");
-	const sendResult = await forwardToolToCentralMcp(
-		"messaging_whatsapp_send",
-		{ phone: operatorPhone, message },
-		systemCtx,
-	);
-
-	// 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 = extractWhatsAppMessageId(sendResult);
-	if (!messageId) {
-		throw new Error(
-			`platform-fault-escalation: WhatsApp send for '${kind}' returned no message id — not recording delivery. ` +
-				`Response: ${JSON.stringify(sendResult).slice(0, 400)}`,
-		);
-	}
-
-	// 4. Durable record: a COMMENT on the orchestrator's work item — an
-	// escalation is a finding the orchestrator/operator triages, not an
-	// assigned task (the fleet-task-placement constraint refuses task rows
-	// without session identity by design).
-	const comment = await (await orpc()).comments.create({
-		data: {
-			work_item_id: config.orchestrator_work_item_id,
-			content: message,
-			source_cli_session_id: null,
-		},
-	});
-
-	// 5. Readback-correct the episode: delivered + linked in one update.
-	await (await orpc()).platform_fault_escalations.update({
-		where: { kind },
-		data: {
-			escalated_at: now.toISOString(),
-			work_item_id: config.orchestrator_work_item_id,
-			delivered_comment_id: comment.id,
-			delivered_message_id: messageId,
-			last_updated_at: now.toISOString(),
-			updated_at: now.toISOString(),
-		},
-	});
-
-	recordEvent({
-		kind: "platform.fault.escalated",
-		payload: {
-			event_kind: kind,
-			count: aggregate.count,
-			sample,
-			last_event_id: lastEvent?.eventId ?? null,
-			last_event_occurred_at: lastEvent?.occurredAt ?? null,
-			work_item_id: config.orchestrator_work_item_id,
-			delivered_comment_id: comment.id,
-			delivered_message_id: messageId,
-		},
-	});
-	return { messageId, workItemId: config.orchestrator_work_item_id };
-}
-
-async function resolveEpisode(episode: EscalationEpisode, quietMinutes: number): Promise<void> {
-	const now = new Date();
-	await (await orpc()).platform_fault_escalations.update({
-		where: { kind: episode.kind },
-		data: { resolved_at: now.toISOString(), updated_at: now.toISOString() },
-	});
-	if (episode.workItemId) {
-		await (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.`,
-				sender_role: "system",
-				sender_name: "platform-fault-escalation",
-			},
-		});
-	}
-	recordEvent({
-		kind: "platform.fault.resolved",
-		payload: { event_kind: episode.kind, quiet_minutes: Math.round(quietMinutes), work_item_id: episode.workItemId },
-	});
-}
+import { loadFaultEscalationConfig } from "./platform-fault-escalation/config.ts";
+import { fetchAggregates } from "./platform-fault-escalation/event-log-queries.ts";
+import { orpc } from "./platform-fault-escalation/orpc-client.ts";
+import {
+	deliverEscalation,
+	resolveEpisode,
+} from "./platform-fault-escalation/delivery.ts";
 
 async function platformFaultEscalationSweep(ctx: { config: ScheduledJobConfig }): Promise<void> {
 	const log = getAppLogger();
-	const config = await loadConfig();
+	const config = await loadFaultEscalationConfig();
 	const now = new Date();
 
 	const aggregates = await fetchAggregates(config.watched_kind_patterns, config.window_minutes);