cursedbelt 2.7.0 → 3.0.0

package/src/server/incidents/notifier.ts

@@ -1,215 +0,0 @@
-/**
- * Turning a state TRANSITION into a message, and sending it exactly once.
- *
- * Everything that decides "does the owner hear about this?" is here, and there
- * is very little of it, because the hard part was done in `store.ts`: this
- * module only ever sees `opened`, `escalated` and `resolved`. There is no
- * de-duplication logic in this file and there must never be — a second dedupe,
- * on a timer, is how a system ends up with two disagreeing answers to "have I
- * already said this?".
- *
- * ── The message the owner actually gets ─────────────────────────────────────
- * The owner's standing complaint about agent hand-offs is that they name a
- * symptom, a command and a credential without saying what any of them are. So
- * an incident message is three sentences with fixed jobs, in this order:
- *
- *   WHAT BROKE      — in words, naming the app. Assume he does not know what
- *                     your daemon, flag, tab or port is.
- *   WHAT IT BLOCKS  — what he cannot do until it is fixed. This is the sentence
- *                     that earns a text message at 2am; if you cannot write it,
- *                     the incident is a `warning`.
- *   WHAT TO DO      — a next step. A command carries its own `cd`, because he
- *                     opens terminals anywhere (`fleet/rules/
- *                     commands-must-run-from-anywhere.md`).
- *
- * ── 🔴 What is deliberately NOT in a message ────────────────────────────────
- * File names, note titles, vault keys, e-mail addresses, anything a person
- * typed. `subject` is an identifier and `facts` are numbers, both enforced at
- * the store (`assertNoContent`). A text message is the least private surface
- * this fleet has and several of its apps are private by construction.
- */
-import type { ChannelMessage, ChannelResult, IncidentChannel } from "./channels";
-import type { IncidentStore } from "./store";
-import type { Incident, IncidentTransitions } from "./types";
-
-export interface IncidentNotifier {
-	/** Send for every transition in `t`. Returns one result per message sent. */
-	announce: (t: IncidentTransitions) => Promise<AnnounceResult[]>;
-	/** The channels registered on this host, for the console's health row. */
-	readonly channels: readonly IncidentChannel[];
-}
-
-export interface AnnounceResult {
-	fingerprint: string;
-	transition: "opened" | "escalated" | "resolved";
-	results: ChannelResult[];
-}
-
-/**
- * How long to wait before trying a BLOCKING incident again when no channel
- * managed to deliver it.
- *
- * 🔴 This exists because of a real hole found on the first live sweep: `roms`'
- * overdue backup opened as blocking while the email channel was still
- * misconfigured, both channels failed, and — because `notifiedAt` was stamped —
- * nothing would ever have tried again. The owner would have had a blocking
- * incident on a board he had no reason to open. The dedupe promise is "you are
- * told ONCE", not "we attempt once": an attempt that reached nobody has not told
- * him anything.
- *
- * It retries at most hourly, and it STOPS the moment any channel reports
- * `delivered` — so a permanently broken channel costs one send an hour, and a
- * working one costs exactly one message, which is the guarantee.
- */
-export const UNDELIVERED_RETRY_MS = 60 * 60 * 1000;
-
-/** Did any channel actually get it out? `skipped` is not delivery. */
-const wasDelivered = (notifyResult: string | null): boolean =>
-	Boolean(notifyResult?.includes("=delivered"));
-
-const factLine = (incident: Incident): string => {
-	const facts = Object.entries(incident.facts ?? {});
-	if (facts.length === 0) return "";
-	return `\n${facts.map(([k, v]) => `${k}: ${v}`).join(" · ")}`;
-};
-
-/** The message for a newly-open (or newly-blocking) incident. */
-export function composeOpened(incident: Incident): ChannelMessage {
-	const tag = incident.severity === "blocking" ? "BLOCKED" : "Heads up";
-	return {
-		severity: incident.severity,
-		subject: `[${tag}] ${incident.title}`,
-		text: [
-			`What broke: ${incident.whatBroke}`,
-			`What it blocks: ${incident.whatItBlocks}`,
-			`What to do: ${incident.whatToDo}`,
-			`(${incident.source} · ${incident.kind} · ${incident.subject})${factLine(incident)}`,
-		].join("\n\n"),
-	};
-}
-
-/**
- * The message for a resolve. It exists so "is it fixed?" is answered without
- * him having to go and look — the same reason the open message exists.
- */
-export function composeResolved(incident: Incident): ChannelMessage {
-	const minutes = Math.max(1, Math.round(((incident.resolvedAt ?? 0) - incident.firstSeen) / 60000));
-	return {
-		severity: incident.severity,
-		subject: `[cleared] ${incident.title}`,
-		text: [
-			`This is no longer happening. It was open for about ${minutes} minute${minutes === 1 ? "" : "s"}.`,
-			`It was: ${incident.whatBroke}`,
-			`(${incident.source} · ${incident.kind} · ${incident.subject})`,
-		].join("\n\n"),
-	};
-}
-
-export interface CreateNotifierOptions {
-	store: IncidentStore;
-	channels: readonly IncidentChannel[];
-	/**
-	 * Called with every channel result, so a host can record channel health.
-	 * `detectChannelHealth` in `detectors.ts` turns a run of failures into its
-	 * own incident — which is why `ChannelMessage.avoid` exists.
-	 */
-	onChannelResult?: (fingerprint: string, result: ChannelResult) => void;
-}
-
-export function createIncidentNotifier(options: CreateNotifierOptions): IncidentNotifier {
-	const { store, channels } = options;
-
-	const dispatch = async (
-		incident: Incident,
-		message: ChannelMessage,
-		transition: AnnounceResult["transition"],
-	): Promise<AnnounceResult> => {
-		// An incident that IS a channel failure must not be announced down the
-		// channel it is about. Without this the first SES outage produces an
-		// endless retry loop against SES.
-		const avoid =
-			incident.kind === "notification-channel-failing" ? [incident.subject] : undefined;
-		const withAvoid: ChannelMessage = avoid ? { ...message, avoid } : message;
-
-		const results: ChannelResult[] = [];
-		for (const channel of channels) {
-			// 🔴 The `avoid` guard lives HERE, not in each channel. It was in every
-			// channel first and a spy channel in the spec walked straight past it —
-			// which is the same hole any channel added later would have had. One
-			// enforcement point, and a new channel inherits it by existing.
-			if (withAvoid.avoid?.includes(channel.key)) {
-				results.push({
-					channel: channel.key,
-					outcome: "skipped",
-					detail: "this message is ABOUT this channel — not sent down it",
-				});
-				continue;
-			}
-			// Channels are awaited in series on purpose: there are at most three,
-			// they are all fast, and a serial loop means the text channel's
-			// delivery-proof read cannot race the email channel's for the same
-			// laptop resources.
-			const result = await channel.send(withAvoid).catch(
-				(err): ChannelResult => ({
-					channel: channel.key,
-					outcome: "failed",
-					detail: err instanceof Error ? err.message.slice(0, 200) : String(err),
-				}),
-			);
-			results.push(result);
-			options.onChannelResult?.(incident.fingerprint, result);
-		}
-		return { fingerprint: incident.fingerprint, transition, results };
-	};
-
-	const summarise = (results: ChannelResult[]): string =>
-		results.map((r) => `${r.channel}=${r.outcome}`).join(" ");
-
-	return {
-		channels,
-		async announce(t) {
-			const out: AnnounceResult[] = [];
-
-			for (const incident of [...t.opened, ...t.escalated]) {
-				const transition = t.opened.includes(incident) ? "opened" : "escalated";
-				const result = await dispatch(incident, composeOpened(incident), transition);
-				// 🔴 Only stamp `notifiedAt` when there was actually a channel to try.
-				// A host with none (a prod deployment that only stores what the Mac
-				// pushes it) has not told him anything, and stamping it there is what
-				// made the resolve message below fire for an open he never saw.
-				if (result.results.length > 0) {
-					store.markNotified([incident.fingerprint], summarise(result.results));
-				}
-				out.push(result);
-			}
-
-			// A blocking incident nobody could be told about is retried, hourly,
-			// until one channel lands it. See `UNDELIVERED_RETRY_MS`.
-			for (const incident of t.unchanged) {
-				if (incident.severity !== "blocking") continue;
-				if (incident.notifiedAt === null) continue;
-				if (wasDelivered(incident.notifyResult)) continue;
-				if (Date.now() - incident.notifiedAt < UNDELIVERED_RETRY_MS) continue;
-				const result = await dispatch(incident, composeOpened(incident), "opened");
-				if (result.results.length > 0) {
-					store.markNotified([incident.fingerprint], summarise(result.results));
-				}
-				out.push(result);
-			}
-
-			for (const incident of t.resolved) {
-				// Never announce a resolve for something whose OPEN was never
-				// announced — the owner would get "cleared: X" for an X he has never
-				// heard of, which reads as a bug in the alerting rather than as good
-				// news. This happens for real: an incident opened, acknowledged and
-				// resolved between two sweeps of a host that had no channels.
-				if (incident.notifiedAt === null) continue;
-				const result = await dispatch(incident, composeResolved(incident), "resolved");
-				store.markResolvedNotified([incident.fingerprint]);
-				out.push(result);
-			}
-
-			return out;
-		},
-	};
-}

package/src/server/incidents/reporter.ts

@@ -1,110 +0,0 @@
-/**
- * The other side of `POST /incidents/report` — how a service that is NOT the
- * console tells the console what it can see.
- *
- * ── Why a service reports rather than being polled ──────────────────────────
- * The console can measure a service's disk, its port and its HTTP status from
- * outside. It cannot measure the things that actually go wrong inside one: an
- * ingest run where every item failed, a queue whose worker is looping on the
- * same error, a store that is refusing writes for a reason of its own. Those
- * facts exist for a few milliseconds inside the process that has them, and the
- * only place they can be turned into an incident is there.
- *
- * ── 🔴 Reporting is a HEARTBEAT, not an event ───────────────────────────────
- * A reporter sends the complete set of conditions that are true right now — the
- * same contract a local check has — and sends it on a schedule whether or not
- * anything is wrong. That is what lets the console clear an incident when the
- * service recovers. A reporter that only posts on failure can open an incident
- * and can never close one, and the owner ends up with a permanently red board,
- * which is the same uselessness as a permanently green one.
- *
- * The dedupe is entirely the console's: post the same thing every five minutes
- * for a week and he is told once. So a reporter needs no state, no "have I said
- * this?" flag, and no backoff — which is why this file is forty lines and not
- * four hundred.
- *
- * ── It never throws, and never blocks the service ───────────────────────────
- * A service whose real work fails because its ALERTING is unreachable is worse
- * than one with no alerting. Every failure here is logged and swallowed, and the
- * console notices the silence by other means (the service's own health probe).
- */
-import type { IncidentReport } from "./types";
-
-export interface IncidentReporterOptions {
-	/** e.g. `http://127.0.0.1:3024/api/station/incidents/report`. */
-	url: string;
-	/** The shared bearer the console's `reporterToken` compares against. */
-	token: string;
-	/** This service's name — the `source` of everything it reports. */
-	source: string;
-	/** A stable key for this reporter, owning the incidents it opens. */
-	checkKey: string;
-	/**
-	 * Every `kind` this reporter can produce. Required, not optional: without it
-	 * the console cannot tell "nothing is wrong" from "nothing was said", so a
-	 * recovered service would stay red for ever. See `ReconcileOptions`.
-	 */
-	kinds: readonly string[];
-	/** Produce the current set of true conditions. Called on every beat. */
-	collect: () => Promise<IncidentReport[]> | IncidentReport[];
-	/** Default 5 minutes. The console dedupes, so this is chosen for the network. */
-	intervalMs?: number;
-	fetchImpl?: typeof fetch;
-	log?: (message: string) => void;
-}
-
-export interface IncidentReporter {
-	/** Send one beat now. Resolves `false` on any failure — it never throws. */
-	beat: () => Promise<boolean>;
-	start: () => void;
-	stop: () => void;
-}
-
-export function createIncidentReporter(options: IncidentReporterOptions): IncidentReporter {
-	const doFetch = options.fetchImpl ?? fetch;
-	const log = options.log ?? ((m: string) => console.warn(`[incidents] ${m}`));
-	const intervalMs = options.intervalMs ?? 5 * 60_000;
-	let timer: ReturnType<typeof setInterval> | null = null;
-
-	const beat = async (): Promise<boolean> => {
-		try {
-			const reports = await options.collect();
-			const res = await doFetch(options.url, {
-				method: "POST",
-				headers: {
-					"content-type": "application/json",
-					authorization: `Bearer ${options.token}`,
-				},
-				body: JSON.stringify({
-					checkKey: options.checkKey,
-					source: options.source,
-					kinds: options.kinds,
-					reports,
-				}),
-				signal: AbortSignal.timeout(10_000),
-			});
-			if (!res.ok) {
-				log(`the console answered ${res.status} — ${reports.length} finding(s) not filed`);
-				return false;
-			}
-			return true;
-		} catch (err) {
-			log(`could not reach the console: ${err instanceof Error ? err.message : String(err)}`);
-			return false;
-		}
-	};
-
-	return {
-		beat,
-		start() {
-			if (timer) return;
-			timer = setInterval(() => void beat(), intervalMs);
-			// Never hold the process open for the sake of its own alerting.
-			timer.unref?.();
-		},
-		stop() {
-			if (timer) clearInterval(timer);
-			timer = null;
-		},
-	};
-}

package/src/server/incidents/routes.ts

@@ -1,314 +0,0 @@
-/**
- * The mountable half — ordinary Hono routes, so any app can expose its incidents
- * without adopting another app's rpc layer (the same reasoning, and the same
- * shape, as `server/notifications/routes.ts`).
- *
- * ```ts
- * // BEFORE the session gate — the machine doors carry their own bearer:
- * mountIncidentMachineRoutes(app, { store, notifier, reporterToken });
- * // INSIDE it — the owner's own surface:
- * mountIncidentOwnerRoutes(app, { store, notifier, sweep, authorize: isOwner });
- * ```
- *
- * ── 🔴 Two doors, two MOUNTS, and that is the whole point ───────────────────
- * `authorize` is the OWNER's session — it guards the list, the acks, the manual
- * sweep and the channel test. `reporterToken` is a shared bearer and guards the
- * two routes a DAEMON uses. They answer different questions ("is this the
- * owner's browser?" and "is this one of my own processes?"), so a reporter can
- * never read the incident list and a browser session can never forge an
- * incident.
- *
- * They were one function first, and the console mounted it inside its session
- * gate. Every beat from binary-server and orch came back
- * `{"error":"unauthorized"}` — from the GATE, so nothing in this module logged
- * anything and the console showed a perfectly calm, empty board. A reporter
- * cannot report that it could not reach the reporting door. Two functions make
- * the mount order a thing you have to get right rather than a thing you can
- * forget, and they stop the opposite mistake too: registering the owner's
- * `GET /incidents` outside the gate, where Hono's first-match would shadow the
- * real one for ever.
- *
- * 🔴 `POST /report` is the ONE route that accepts incident text from off-box, so
- * it is also the one that has to be paranoid about it: every field is length-
- * capped and `facts` is re-validated through the store's `assertNoContent`
- * before anything is written. A reporter is trusted to be honest, not to be
- * correct.
- */
-import type { Hono } from "hono";
-import type { IncidentChannel } from "./channels";
-import type { IncidentNotifier } from "./notifier";
-import { assertNoContent, type IncidentStore } from "./store";
-import type { IncidentReport, IncidentSeverity } from "./types";
-import type { SweepResult } from "./checks";
-
-const noStore = { "cache-control": "no-store" } as const;
-
-/** Long enough for three real sentences, short enough that nobody pastes a log in. */
-const MAX_FIELD = 600;
-const MAX_REPORTS = 100;
-
-export interface IncidentRoutesOptions {
-	store: IncidentStore;
-	/** Owner-only gate for the read + write surface. Return false to 403. */
-	authorize: (c: unknown) => boolean | Promise<boolean>;
-	/** Run the checks now. Omitted on a host that runs no detectors (prod). */
-	sweep?: () => Promise<SweepResult>;
-	/** Used to announce anything a remote report opens, and to list channel health. */
-	notifier?: IncidentNotifier;
-	/** Shared bearer for `POST /report`. Omitted, the route is not mounted. */
-	reporterToken?: string;
-	/**
-	 * Deliver one message as this host. Mounted as `POST /relay-email` and used
-	 * by the local console, which cannot reach SES — see `channels.ts`.
-	 */
-	relayEmail?: (msg: {
-		subject: string;
-		text: string;
-		html?: string;
-	}) => Promise<{ sent: boolean; reason?: string }>;
-	/** The last sweep, for the health route. */
-	lastSweep?: () => SweepResult | null;
-	/** Send a test message down one channel, so the owner can prove it works. */
-	channelsOf?: () => readonly IncidentChannel[];
-}
-
-const str = (v: unknown, fallback = ""): string =>
-	typeof v === "string" ? v.slice(0, MAX_FIELD) : fallback;
-
-/** Parse one posted report defensively. Throws with a usable message. */
-function parseReport(raw: unknown): IncidentReport {
-	if (!raw || typeof raw !== "object") throw new Error("each report must be an object");
-	const r = raw as Record<string, unknown>;
-	const severity: IncidentSeverity = r.severity === "blocking" ? "blocking" : "warning";
-	const report: IncidentReport = {
-		source: str(r.source),
-		kind: str(r.kind),
-		subject: str(r.subject),
-		severity,
-		title: str(r.title),
-		whatBroke: str(r.whatBroke),
-		whatItBlocks: str(r.whatItBlocks),
-		whatToDo: str(r.whatToDo),
-		...(r.facts && typeof r.facts === "object"
-			? { facts: r.facts as IncidentReport["facts"] }
-			: {}),
-	};
-	for (const field of ["source", "kind", "subject", "title", "whatBroke"] as const) {
-		if (!report[field]) throw new Error(`report is missing "${field}"`);
-	}
-	// The privacy gate, applied to off-box input before it can reach a phone.
-	assertNoContent(report);
-	return report;
-}
-
-/**
- * The OWNER's surface: the list, the acks, the health strip, the manual sweep,
- * the channel test. Mount it INSIDE the app's session gate.
- */
-export function mountIncidentOwnerRoutes(
-	app: Hono,
-	options: IncidentRoutesOptions,
-	basePath = "/incidents",
-): void {
-	const { store } = options;
-
-	const guard = async (c: { json: (b: unknown, s?: number) => Response }): Promise<Response | null> =>
-		(await options.authorize(c)) ? null : c.json({ error: "forbidden" }, 403);
-
-	app.get(`${basePath}`, async (c) => {
-		const denied = await guard(c);
-		if (denied) return denied;
-		const state = c.req.query("state");
-		const incidents = store.list({
-			state:
-				state === "all"
-					? undefined
-					: state === "resolved"
-						? "resolved"
-						: state === "open"
-							? "open"
-							: "active",
-			limit: Number(c.req.query("limit") ?? 200),
-		});
-		return c.json({ incidents }, 200, noStore);
-	});
-
-	app.post(`${basePath}/:fingerprint/ack`, async (c) => {
-		const denied = await guard(c);
-		if (denied) return denied;
-		const ok = store.acknowledge(decodeURIComponent(c.req.param("fingerprint")));
-		return c.json({ ok }, ok ? 200 : 404, noStore);
-	});
-
-	app.get(`${basePath}/health`, async (c) => {
-		const denied = await guard(c);
-		if (denied) return denied;
-		return c.json(
-			{
-				channels: (options.channelsOf?.() ?? options.notifier?.channels ?? []).map((ch) => ({
-					key: ch.key,
-					label: ch.label,
-				})),
-				lastSweep: options.lastSweep?.() ?? null,
-				sweepable: Boolean(options.sweep),
-			},
-			200,
-			noStore,
-		);
-	});
-
-	if (options.sweep) {
-		app.post(`${basePath}/sweep`, async (c) => {
-			const denied = await guard(c);
-			if (denied) return denied;
-			const result = await options.sweep?.();
-			if (!result) return c.json({ error: "no detectors on this host" }, 400, noStore);
-			const announced = options.notifier ? await options.notifier.announce(result.transitions) : [];
-			return c.json({ result, announced }, 200, noStore);
-		});
-	}
-
-	if (options.channelsOf) {
-		app.post(`${basePath}/test/:channel`, async (c) => {
-			const denied = await guard(c);
-			if (denied) return denied;
-			const key = c.req.param("channel");
-			const channel = options.channelsOf?.().find((ch) => ch.key === key);
-			if (!channel) return c.json({ error: `no channel "${key}" on this host` }, 404, noStore);
-			// Sent at `blocking` because that is the severity whose delivery matters —
-			// a test that exercises the in-app path and skips the phone proves nothing.
-			const result = await channel.send({
-				severity: "blocking",
-				subject: "[test] fleet incident alerts",
-				text: "This is the console proving the channel works. Nothing is wrong. No action needed.",
-			});
-			return c.json({ result }, 200, noStore);
-		});
-	}
-}
-
-/**
- * The MACHINE doors: `POST /report`, which another service beats its findings
- * into, and `POST /relay-email`, which a host that cannot send mail hands a
- * message to. Both carry a shared bearer.
- *
- * 🔴 **Mount this BEFORE the session gate, and never call it with `authorize`
- * expecting it to matter — it registers no route a browser should reach.**
- * Mounting the two together inside a cookie gate is the trap this split exists
- * to make impossible: every beat from binary-server and orch came back
- * `{"error":"unauthorized"}` from the gate, so no log line in this module said
- * anything was wrong and the console rendered a perfectly calm, empty board.
- * A reporter cannot report the failure to reach the reporting door.
- *
- * Keeping them in one function also risked the opposite mistake — registering
- * the owner's `GET /incidents` outside the gate, where Hono's first-match would
- * have shadowed the real one for ever.
- */
-export function mountIncidentMachineRoutes(
-	app: Hono,
-	options: Pick<IncidentRoutesOptions, "store" | "notifier" | "reporterToken" | "relayEmail">,
-	basePath = "/incidents",
-): void {
-	const { store } = options;
-	if (options.reporterToken) {
-		app.post(`${basePath}/report`, async (c) => {
-			const header = c.req.header("authorization") ?? "";
-			const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
-			// Length-first compare then constant-time-ish equality; the token is a
-			// shared secret between our own daemons, not a user credential.
-			if (
-				presented.length !== options.reporterToken?.length ||
-				presented !== options.reporterToken
-			) {
-				return c.json({ error: "forbidden" }, 403, noStore);
-			}
-			const body = (await c.req.json().catch(() => null)) as {
-				checkKey?: unknown;
-				source?: unknown;
-				kinds?: unknown;
-				reports?: unknown;
-			} | null;
-			const checkKey = str(body?.checkKey);
-			const source = str(body?.source);
-			const rawReports = Array.isArray(body?.reports) ? body.reports : null;
-			if (!checkKey || !source || !rawReports) {
-				return c.json(
-					{ error: "checkKey, source and reports[] are required" },
-					400,
-					noStore,
-				);
-			}
-			if (rawReports.length > MAX_REPORTS) {
-				return c.json({ error: `at most ${MAX_REPORTS} reports per call` }, 400, noStore);
-			}
-			let reports: IncidentReport[];
-			try {
-				reports = rawReports.map(parseReport);
-			} catch (err) {
-				return c.json(
-					{ error: err instanceof Error ? err.message : "bad report" },
-					400,
-					noStore,
-				);
-			}
-			// A reporter declares the kinds it is authoritative for, exactly as a
-			// local check does — without them a remote service could never clear its
-			// own incidents, and every transient blip would stay red forever.
-			const kinds = Array.isArray(body?.kinds)
-				? (body.kinds as unknown[]).filter((k): k is string => typeof k === "string")
-				: [...new Set(reports.map((r) => r.kind))];
-			const transitions = store.reconcile(checkKey, reports, {
-				namespaces: kinds.map((k) => `${source}:${k}:`),
-			});
-			const announced = options.notifier ? await options.notifier.announce(transitions) : [];
-			return c.json(
-				{
-					opened: transitions.opened.length,
-					escalated: transitions.escalated.length,
-					resolved: transitions.resolved.length,
-					unchanged: transitions.unchanged.length,
-					announced,
-				},
-				200,
-				noStore,
-			);
-		});
-	}
-
-	if (options.relayEmail) {
-		app.post(`${basePath}/relay-email`, async (c) => {
-			const header = c.req.header("authorization") ?? "";
-			const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
-			if (
-				!options.reporterToken ||
-				presented.length !== options.reporterToken.length ||
-				presented !== options.reporterToken
-			) {
-				return c.json({ error: "forbidden" }, 403, noStore);
-			}
-			const body = (await c.req.json().catch(() => null)) as {
-				subject?: unknown;
-				text?: unknown;
-				html?: unknown;
-			} | null;
-			const subject = str(body?.subject);
-			const text = typeof body?.text === "string" ? body.text.slice(0, 4000) : "";
-			if (!subject || !text) return c.json({ error: "subject and text required" }, 400, noStore);
-			// 🔴 The REASON crosses the wire, not just the boolean. `{sent:false}`
-			// alone made the local console report "the prod console accepted the
-			// request but its mailer declined" — true, useless, and indistinguishable
-			// between "mail is off on that host" and "SES refused the address". The
-			// relay is the only place that knows.
-			const outcome = await options.relayEmail?.({
-				subject,
-				text,
-				...(typeof body?.html === "string" ? { html: body.html.slice(0, 20_000) } : {}),
-			});
-			return c.json(
-				{ sent: Boolean(outcome?.sent), ...(outcome?.reason ? { reason: outcome.reason } : {}) },
-				200,
-				noStore,
-			);
-		});
-	}
-}