@teamscala/service-boot 0.23.417 → 0.23.419

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);

package/src/register-registry-page-route/page-data-shared.ts

@@ -0,0 +1,124 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Shared Puck-page-data helpers for the resolved-graph → pageData conversion:
+ * the local PuckData structural type, JSON extraction with an honest null on
+ * malformed input, layout-default application, region root-prop picking, the
+ * RegionEntry shape, and the unresolved-region-slot warn. Plus the brand-token
+ * prologue shared by all three render branches.
+ *
+ * Split out of resolve-page-data.ts (547 lines) — byte-for-byte moves; only
+ * closure variables became explicit parameters.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+/**
+ * Local structural type for Puck page data. Avoids a type-only import of
+ * `@puckeditor/core`, which is NOT a runtime dependency — `deps-derived-from-source`
+ * excludes whole-statement type-only imports, so the bare specifier has no
+ * installed package to resolve against at publish typecheck time. The shape used
+ * here (root/content/zones) is all this module reads or constructs.
+ */
+export type PuckData = {
+	root: { props?: Record<string, unknown> };
+	content: unknown[];
+	zones?: Record<string, unknown>;
+};
+
+export const EMPTY_PUCK_DATA: PuckData = { root: { props: {} }, content: [] };
+
+// Returns null on malformed JSON (observed via warn log) instead of a silent
+// masking empty fallback — protective-layers-fail-explicitly. Callers default
+// to EMPTY_PUCK_DATA where an empty render is the intended degradation.
+export function extractPuckData(source: Record<string, unknown>): PuckData | null {
+	const raw = source.puck_data ?? source.puckData;
+	if (!raw) return EMPTY_PUCK_DATA;
+	if (typeof raw === "string") {
+		try {
+			return JSON.parse(raw) as PuckData;
+		} catch (err) {
+			getAppLogger().warn(
+				"[extractPuckData] malformed puck_data JSON — rendering empty",
+				{ err },
+			);
+			return null;
+		}
+	}
+	return raw as PuckData;
+}
+
+export function applyLayoutDefaults(
+	puckData: PuckData,
+	defaults: Record<string, string>,
+): void {
+	if (!defaults || Object.keys(defaults).length === 0) return;
+	const data = puckData as { root?: { props?: Record<string, unknown> } };
+	if (!data.root) data.root = { props: {} };
+	if (!data.root.props) data.root.props = {};
+	for (const [key, value] of Object.entries(defaults)) {
+		if (data.root.props[key] == null) data.root.props[key] = value;
+	}
+}
+
+export function pickRootProp<T>(regions: RegionEntry[], key: string): T | undefined {
+	for (const region of regions) {
+		const props = (
+			region.puckData as { root?: { props?: Record<string, unknown> } } | null
+		)?.root?.props;
+		const value = props?.[key];
+		if (value != null && value !== "") return value as T;
+	}
+	return undefined;
+}
+
+export interface RegionEntry {
+	slot: string;
+	puckData: PuckData;
+	pageId: string;
+	website?: { slug: string; name: string; organisation_id?: string | null };
+	metaTitle?: string | null;
+	metaDescription?: string | null;
+}
+
+// A region slot the operator DECLARED (resource_loader.region_slots) whose
+// source did not resolve used to vanish with no signal anywhere — the page
+// rendered minus a region while the page, source, attributes, template and
+// tree builder all looked innocent (measured 2026-08-18: a footer region
+// added to a report produced no footer and no diagnostic; the cause was the
+// boot-time config capture named in the message). One warn per slot per
+// process, throttled like the block-coverage guard in the caller, so the hot
+// path never spams it.
+const unresolvedRegionSlotsLogged = new Set<string>();
+
+export function warnUnresolvedRegionSlot(slot: string): void {
+	if (unresolvedRegionSlotsLogged.has(slot)) return;
+	unresolvedRegionSlotsLogged.add(slot);
+	getAppLogger().warn(
+		`[resolve-page-data] region slot "${slot}" is declared in the resource_loader config but no source resolved for it — the region is omitted from this render. A resource_loader edit reaches a booted service only after a restart.`,
+	);
+}
+
+/** The resolved brand tokens every branch reads (the old file's shared prologue). */
+export function readBrandTokens(resolved: Record<string, unknown>): {
+	brand: Record<string, unknown>;
+	primaryColor: string;
+	headingFont: string | null;
+	bodyFont: string | null;
+	logo: { light: string | null; dark: string | null; brand: string | null };
+	brandTheme: string | undefined;
+} {
+	const brand = (resolved.brand as Record<string, unknown>) ?? {};
+	const primaryColor = (brand.primaryColor as string) ?? "";
+	const headingFont = (brand.headingFont as string) ?? null;
+	const bodyFont = (brand.bodyFont as string) ?? null;
+	const logo = (brand.logo as {
+		light: string | null;
+		dark: string | null;
+		brand: string | null;
+	}) ?? { light: null, dark: null, brand: null };
+	const brandTheme = typeof brand.theme === "string" ? brand.theme : undefined;
+	return { brand, primaryColor, headingFont, bodyFont, logo, brandTheme };
+}