@openlup/platform 0.16.0 → 0.18.0

package/src/communications/contribution.ts

@@ -0,0 +1,33 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Host-selected schema inventory: managed and direct installations have different objects. */
+export function createCommunicationsContribution(options: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  routes?: Contribution["routes"];
+  handlers?: Contribution["handlers"];
+  schedules?: Contribution["schedules"];
+  requiredPorts?: readonly string[];
+}): Contribution {
+  const routes = options.routes ?? [];
+  const handlers = options.handlers ?? [];
+  const schedules = options.schedules ?? [];
+  return {
+    manifest: {
+      name: "@openlup/platform", version: options.version, kind: "rail",
+      module: {
+        id: "communications", kind: "capability", provides: ["./communications", "./communications/contracts"],
+        dependsOn: [
+          { module: "data", entries: ["./data"] },
+          { module: "identity", entries: ["./identity"] },
+          { module: "http", entries: ["./http"] },
+        ],
+      },
+      requiredSchema: options.requiredSchema,
+      emits: [], handles: handlers.map((handler) => handler.eventType),
+      schedules: schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), routes: routes.map((route) => route.id),
+      requiredPorts: [...new Set(options.requiredPorts ?? [])], env: [],
+    },
+    handlers, schedules, routes,
+  };
+}

package/src/communications/deliveryReconciliation.ts

@@ -0,0 +1,108 @@
+export interface DeliveryPollCandidate {
+  id: string;
+  messageId: string;
+}
+
+export interface DeliveryStatusRead {
+  ok: boolean;
+  httpStatus: number;
+  recipientEmail: string | null;
+}
+
+/** The host maps its protocol to an opaque event type and terminal classification. */
+export interface DeliveryPollObservation {
+  eventType: string;
+  terminal: boolean;
+}
+
+export interface DeliveryReconciliationPort {
+  findFrozenSends(input: { now: string; graceMinutes: number; limit: number }): Promise<DeliveryPollCandidate[]>;
+  applyPolledEvent(input: {
+    sendId: string;
+    messageId: string;
+    eventType: string;
+    eventAt: string;
+    recipientEmail: string | null;
+  }): Promise<void>;
+  recordPollAttempt(input: { sendId: string; attemptedAt: string }): Promise<void>;
+  recordSendNotFound(input: { sendId: string; threshold: number }): Promise<{ abandoned: boolean }>;
+}
+
+export const DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND = 3;
+
+export interface DeliveryReadFailureBreakdown {
+  notFound: number;
+  authFailed: number;
+  network: number;
+  providerError: number;
+  other: number;
+}
+
+export interface DeliveryReconciliationResult {
+  checked: number;
+  reconciled: number;
+  stillPending: number;
+  terminalPolled: number;
+  failures: number;
+  abandoned: number;
+  failureBreakdown: DeliveryReadFailureBreakdown;
+}
+
+function classifyReadFailure(breakdown: DeliveryReadFailureBreakdown, httpStatus: number): void {
+  if (httpStatus === 404) breakdown.notFound += 1;
+  else if (httpStatus === 401 || httpStatus === 403) breakdown.authFailed += 1;
+  else if (httpStatus === 0) breakdown.network += 1;
+  else if (httpStatus >= 500 && httpStatus <= 599) breakdown.providerError += 1;
+  else breakdown.other += 1;
+}
+
+/** Sequential bounded polling around one host-owned atomic convergence writer. */
+export async function runDeliveryReconciliation<Read extends DeliveryStatusRead>(input: {
+  port: DeliveryReconciliationPort;
+  readEmail: (messageId: string) => Promise<Read>;
+  observationFor: (read: Read) => DeliveryPollObservation | null;
+  now: string;
+  graceMinutes: number;
+  limit: number;
+}): Promise<DeliveryReconciliationResult> {
+  const result: DeliveryReconciliationResult = {
+    checked: 0, reconciled: 0, stillPending: 0, terminalPolled: 0, failures: 0, abandoned: 0,
+    failureBreakdown: { notFound: 0, authFailed: 0, network: 0, providerError: 0, other: 0 },
+  };
+  const frozen = await input.port.findFrozenSends({ now: input.now, graceMinutes: input.graceMinutes, limit: input.limit });
+  for (const send of frozen) {
+    result.checked += 1;
+    const read = await input.readEmail(send.messageId);
+    if (read.httpStatus !== 404) {
+      try {
+        await input.port.recordPollAttempt({ sendId: send.id, attemptedAt: input.now });
+      } catch {
+        // Fairness bookkeeping failure must not discard observed delivery truth.
+        result.failures += 1;
+      }
+    }
+    if (!read.ok) {
+      result.failures += 1;
+      classifyReadFailure(result.failureBreakdown, read.httpStatus);
+      if (read.httpStatus === 404) {
+        const { abandoned } = await input.port.recordSendNotFound({ sendId: send.id, threshold: DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND });
+        if (abandoned) result.abandoned += 1;
+      }
+      continue;
+    }
+    const observation = input.observationFor(read);
+    if (!observation) {
+      result.stillPending += 1;
+      continue;
+    }
+    try {
+      await input.port.applyPolledEvent({ sendId: send.id, messageId: send.messageId,
+        eventType: observation.eventType, eventAt: input.now, recipientEmail: read.recipientEmail });
+      result.reconciled += 1;
+      if (observation.terminal) result.terminalPolled += 1;
+    } catch {
+      result.failures += 1;
+    }
+  }
+  return result;
+}

package/src/communications/emailEgress.ts

@@ -0,0 +1,111 @@
+import type { AuthEmailTransportPort, AuthEmailTransportResult } from "./contracts/authEmail.js";
+import type { EmailMessage, EmailSendResult, EmailTransport } from "./emailTransport.js";
+
+export interface EmailEgressContext {
+  mode: "production" | "sandbox_direct" | "sandbox_sink";
+  reason: string;
+  intendedRecipient: string;
+  recipient: string;
+  /** Selected by the host; consumed only by its concrete sender, never logged. */
+  credential: string;
+  environmentTag: "production" | "non_production";
+}
+
+export type EmailEgressDecision = EmailEgressContext | { mode: "drop"; reason: string } | { mode: "blocked"; reason: string };
+export type EmailEgressPolicy = (intendedRecipient: string) => EmailEgressDecision | Promise<EmailEgressDecision>;
+
+const admitted = new WeakSet<EmailTransport>();
+const admittedAuth = new WeakSet<AuthEmailTransportPort>();
+
+/**
+ * Host composition bridge for an implementation that already enforces egress
+ * internally. This is a trust boundary: its sender must itself refuse unknown
+ * policy before effects. New network adapters should use createGuardedEmailTransport.
+ * Neither a provider name nor an object property establishes admission.
+ */
+export function admitPolicyEnforcedEmailTransport<T extends EmailTransport>(transport: T): T {
+  admitted.add(transport);
+  return transport;
+}
+
+/** Mandatory boundary for supported injected transports; raw objects fail closed. */
+export function guardEmailTransport(transport: EmailTransport): EmailTransport {
+  if (admitted.has(transport)) return transport;
+  return { providerKind: transport.providerKind, send: async () => refused("email_egress_unadmitted") };
+}
+
+/** Construct a network adapter whose sender sees only a validated host decision. */
+export function createGuardedEmailTransport(input: {
+  providerKind: string;
+  policy: EmailEgressPolicy;
+  send: (message: EmailMessage, context: Readonly<EmailEgressContext>) => Promise<EmailSendResult>;
+}): EmailTransport {
+  return admitPolicyEnforcedEmailTransport({
+    providerKind: input.providerKind,
+    async send(message) {
+      let decision: unknown;
+      try { decision = await input.policy(message.to); }
+      catch { return refused("email_egress_policy_unavailable"); }
+      if (!validDecision(decision, message.to)) return refused("email_egress_policy_invalid");
+      if (decision.mode === "blocked") return refused("email_egress_blocked", decision.reason);
+      if (decision.mode === "drop") return {
+        outcome: { ok: true, resendId: null, httpStatus: 0, providerError: null, aborted: false,
+          suppressed: "drop", egressMode: "drop", egressReason: decision.reason },
+        providerResponse: { suppressed: "drop", egress_reason: decision.reason },
+      };
+      const context = Object.freeze({ ...decision });
+      const result = await input.send({ ...message, to: context.recipient }, context);
+      return { ...result, outcome: { ...result.outcome, egressMode: context.mode, egressReason: context.reason } };
+    },
+  });
+}
+
+function validDecision(value: unknown, intended: string): value is EmailEgressDecision {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const d = value as Record<string, unknown>;
+  // Policy diagnostics are bounded codes, never arbitrary exception/secret text.
+  if (typeof d.reason !== "string" || !/^[a-z][a-z0-9_]{0,79}$/.test(d.reason)) return false;
+  if (d.mode === "drop" || d.mode === "blocked") return Object.keys(d).every((key) => key === "mode" || key === "reason");
+  if (d.mode !== "production" && d.mode !== "sandbox_direct" && d.mode !== "sandbox_sink") return false;
+  if (!Object.keys(d).every((key) => ["mode", "reason", "intendedRecipient", "recipient", "credential", "environmentTag"].includes(key))) return false;
+  if (!mailbox(intended) || d.intendedRecipient !== intended || !mailbox(d.recipient)) return false;
+  if (d.mode !== "sandbox_sink" && d.recipient !== intended) return false;
+  if (typeof d.credential !== "string" || !d.credential.trim()) return false;
+  return d.environmentTag === (d.mode === "production" ? "production" : "non_production");
+}
+
+function mailbox(value: unknown): value is string {
+  return typeof value === "string" && /^[^\s@,;<>]+@[^\s@,;<>]+\.[^\s@,;<>]+$/.test(value);
+}
+
+function refused(code: string, reason?: string): EmailSendResult {
+  return { outcome: { ok: false, resendId: null, httpStatus: 0, providerError: code, aborted: false,
+    ...(reason ? { egressReason: reason } : {}) }, providerResponse: { egress_reason: code } };
+}
+
+/** Preserve the Auth envelope/result mapping while retaining package admission. */
+export function createAuthEmailTransport(transport: EmailTransport): AuthEmailTransportPort {
+  const guarded = guardEmailTransport(transport);
+  const auth: AuthEmailTransportPort = {
+    providerKind: transport.providerKind,
+    async send(message) {
+      const result = await guarded.send({ from: message.sender, to: message.recipient,
+        subject: message.subject, html: message.html, text: message.text });
+      return { outcome: { ...result.outcome, messageId: result.outcome.resendId }, providerResponse: result.providerResponse };
+    },
+  };
+  admittedAuth.add(auth);
+  return auth;
+}
+
+/** Raw Auth closures must compose through the admitted email transport bridge. */
+export function guardAuthEmailTransport(transport: AuthEmailTransportPort): AuthEmailTransportPort {
+  if (admittedAuth.has(transport)) return transport;
+  return {
+    providerKind: transport.providerKind,
+    async send(): Promise<AuthEmailTransportResult> {
+      const result = refused("email_egress_unadmitted");
+      return { outcome: { ...result.outcome, messageId: null }, providerResponse: result.providerResponse };
+    },
+  };
+}

package/src/communications/emailHealthAssessment.ts

@@ -0,0 +1,106 @@
+import type { EmailHealthMetrics } from "./emailHealthMetricsPort.js";
+
+/**
+ * Pure email-health assessment layer: env-derived thresholds plus the
+ * healthy/unhealthy verdict over the delivery metrics. Extracted from
+ * `api/_cron/emailHealthWatchdogJob.ts` (which sat at the 300-LOC source cap)
+ * so the incident-driven `permanent_delivery_failure` breach could land here
+ * with unit coverage and no database in the loop.
+ */
+
+type Env = Record<string, string | undefined>;
+
+export interface EmailHealthThresholds {
+  windowMinutes: number;
+  stuckMinutes: number;
+  minAttemptsForRatio: number;
+  maxFailureRatio: number;
+  maxStuck: number;
+  /**
+   * Absolute ceiling on in-window deliveries that ended `status='failed'`
+   * (handler-final loss of a customer notification: outbox discard,
+   * max-attempts exhaustion). Default 0 — a single lost email breaches.
+   * Bounces/complaints are separate statuses and stay ratio-only.
+   */
+  maxPermanentFailures: number;
+}
+
+export interface EmailHealthBreach {
+  code: string;
+  detail: string;
+}
+
+export interface EmailHealthAssessment {
+  healthy: boolean;
+  failureRatio: number;
+  breaches: EmailHealthBreach[];
+}
+
+export function readEmailHealthThresholds(env: Env): EmailHealthThresholds {
+  return {
+    windowMinutes: positiveInt(env.EMAIL_HEALTH_WINDOW_MINUTES, 60),
+    stuckMinutes: positiveInt(env.EMAIL_HEALTH_STUCK_MINUTES, 30),
+    minAttemptsForRatio: positiveInt(env.EMAIL_HEALTH_MIN_ATTEMPTS_FOR_RATIO, 5),
+    maxFailureRatio: clampRatio(env.EMAIL_HEALTH_MAX_FAILURE_RATIO, 0.5),
+    maxStuck: nonNegativeInt(env.EMAIL_HEALTH_MAX_STUCK, 0),
+    maxPermanentFailures: nonNegativeInt(env.EMAIL_HEALTH_MAX_PERMANENT_FAILURES, 0),
+  };
+}
+
+/**
+ * Pure decision: turn raw counts into a healthy/unhealthy verdict. Kept side
+ * effect-free so the thresholds logic is unit-tested without a database.
+ */
+export function evaluateEmailHealth(
+  metrics: EmailHealthMetrics,
+  thresholds: EmailHealthThresholds,
+): EmailHealthAssessment {
+  const failureRatio = metrics.attempted > 0 ? metrics.failed / metrics.attempted : 0;
+  const breaches: EmailHealthBreach[] = [];
+
+  if (metrics.attempted >= thresholds.minAttemptsForRatio && failureRatio > thresholds.maxFailureRatio) {
+    breaches.push({
+      code: "failure_ratio",
+      detail: `${metrics.failed}/${metrics.attempted} (${(failureRatio * 100).toFixed(1)}%) > ${(thresholds.maxFailureRatio * 100).toFixed(1)}%`,
+    });
+  }
+  // Absolute, ratio-independent: one terminally-failed delivery is one
+  // customer notification we finally did not send. Incident 2026-07-24: a
+  // single discarded payment-recovery email stayed invisible because the
+  // ratio breach needs minAttemptsForRatio sends in the window.
+  if (metrics.permanentFailures > thresholds.maxPermanentFailures) {
+    breaches.push({
+      code: "permanent_delivery_failure",
+      detail: `${metrics.permanentFailures} delivery(ies) terminally failed > ${thresholds.maxPermanentFailures}`,
+    });
+  }
+  if (metrics.stuckProcessing > thresholds.maxStuck) {
+    breaches.push({
+      code: "stuck_processing",
+      detail: `${metrics.stuckProcessing} email(s) stuck in 'processing' > ${thresholds.stuckMinutes}m`,
+    });
+  }
+  if (metrics.stuckScheduled > thresholds.maxStuck) {
+    breaches.push({
+      code: "stuck_scheduled",
+      detail: `${metrics.stuckScheduled} scheduled email(s) overdue and undispatched`,
+    });
+  }
+
+  return { healthy: breaches.length === 0, failureRatio, breaches };
+}
+
+function positiveInt(raw: string | undefined, fallback: number): number {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+
+function nonNegativeInt(raw: string | undefined, fallback: number): number {
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+function clampRatio(raw: string | undefined, fallback: number): number {
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : fallback;
+}

package/src/communications/emailHealthMetricsPort.ts

@@ -0,0 +1,17 @@
+export interface EmailHealthMetrics {
+  attempted: number;
+  sent: number;
+  failed: number;
+  delayed: number;
+  /**
+   * In-window rows that ended `status='failed'` — handler-final loss of a
+   * customer notification (outbox discard / max-attempts). Distinct from
+   * `failed` above, which also counts bounces/complaints/missed for the
+   * ratio signal.
+   */
+  permanentFailures: number;
+  /** `processing` rows whose last transition is older than the stuck threshold. */
+  stuckProcessing: number;
+  /** `planned`/`queued` rows past their `expected_send_at` but still not sent. */
+  stuckScheduled: number;
+}

package/src/communications/emailNotificationControl.ts

@@ -0,0 +1,28 @@
+export interface EmailNotificationControlPort {
+  isEnabled(slug: string, signal: AbortSignal): Promise<boolean>;
+}
+
+export interface EmailNotificationControlClient {
+  from(table: string): EmailNotificationControlQueryBuilder;
+}
+
+interface EmailNotificationControlQueryBuilder {
+  select(columns: string): EmailNotificationControlQueryBuilder;
+  eq(column: string, value: unknown): EmailNotificationControlQueryBuilder;
+  maybeSingle(): PromiseLike<{ data: unknown; error: { code?: string; message?: string } | null }>;
+}
+
+export function createEmailNotificationControlPort(
+  client: EmailNotificationControlClient,
+  createPolicy: (client: EmailNotificationControlClient) => { shouldDeliver(input: { slug: string; signal: AbortSignal }): Promise<{ allow: boolean }> },
+): EmailNotificationControlPort {
+  const policy = createPolicy(client);
+  return {
+    isEnabled(slug: string, signal: AbortSignal): Promise<boolean> {
+      return policy.shouldDeliver({ slug, signal }).then((decision) => decision.allow);
+    },
+  };
+}
+
+// Compatibility alias for the pre-neutralization lifecycle consumer.
+export const createSupabaseEmailNotificationControlPort = createEmailNotificationControlPort;

package/src/communications/emailObservation.ts

@@ -0,0 +1,43 @@
+/** An authenticated, decoded, environment-admitted observation. Evidence is opaque. */
+export interface EmailObservation {
+  eventType: string;
+  eventAt: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface EmailObservationPort {
+  findSend(messageId: string): Promise<{ id: string } | null>;
+  applyObservation(observation: EmailObservation & { sendId: string; messageId: string }): Promise<void>;
+  recordAttempt(attempt: EmailObservationDisposition): Promise<void>;
+}
+
+export type EmailObservationDisposition =
+  | { outcome: "send_not_found" }
+  | { outcome: "processed"; sendId: string };
+
+/** Lookup/apply failures propagate; attempt telemetry cannot overturn authoritative success. */
+export async function processEmailObservation(input: {
+  port: EmailObservationPort;
+  messageId: string;
+  // Construct evidence only after a local send is found (including clock reads).
+  observation: () => EmailObservation;
+}): Promise<EmailObservationDisposition> {
+  const send = await input.port.findSend(input.messageId);
+  let disposition: EmailObservationDisposition;
+  if (!send) {
+    disposition = { outcome: "send_not_found" };
+  } else {
+    await input.port.applyObservation({
+      sendId: send.id,
+      messageId: input.messageId,
+      ...input.observation(),
+    });
+    disposition = { outcome: "processed", sendId: send.id };
+  }
+  try {
+    await input.port.recordAttempt(disposition);
+  } catch {
+    // Best-effort telemetry is separate from durable convergence.
+  }
+  return disposition;
+}

package/src/communications/emailTransport.ts

@@ -0,0 +1,167 @@
+import { admitPolicyEnforcedEmailTransport } from "./emailEgress.js";
+/** Provider-agnostic transport contract, outcome projection and capture transport. */
+export interface EmailMessage {
+  from: string;
+  to: string;
+  subject: string;
+  html: string;
+  /** Optional plain-text alternative; omitted from the outbound payload when absent. */
+  text?: string;
+  /** Optional reply mailbox; omitted entirely when the caller does not set it. */
+  replyTo?: string;
+  /** Stable outbound request key retained by the concrete transport for a limited window. */
+  idempotencyKey?: string;
+  /** Base64 content only; remote URLs and filesystem paths are not supported. */
+  attachments?: ReadonlyArray<{ filename: string; content: string }>;
+  /** Cancels the in-flight send when the worker's per-row timeout fires. */
+  signal?: AbortSignal;
+}
+
+/** Transport results preserve existing reference wire shapes. */
+export interface EmailSendOutcome {
+  ok: boolean;
+  /** Legacy identifier retained for reference result compatibility. */
+  resendId: string | null;
+  httpStatus: number;
+  providerError: string | null;
+  providerErrorCode?: string | null;
+  aborted: boolean;
+  suppressed?: "drop" | null;
+  egressMode?: "production" | "sandbox_direct" | "sandbox_sink" | "drop";
+  egressReason?: string;
+}
+export interface EmailSendResult {
+  outcome: EmailSendOutcome;
+  providerResponse: Record<string, unknown>;
+}
+
+export type EmailSendSkipReason = "admin_disabled" | "egress_suppressed";
+
+export interface EmailSendOutcomeLike {
+  ok: boolean;
+  resendId: string | null;
+  providerError: string | null;
+  aborted?: boolean;
+  adminDisabled?: boolean;
+  suppressed?: "drop" | null;
+  skipReason?: EmailSendSkipReason | null;
+}
+
+/** Converts the transport's legacy identifier field at the transport boundary. */
+export function emailTransportMessageId(outcome: EmailSendOutcomeLike): string | null {
+  return outcome.resendId;
+}
+
+/** Maps the neutral message identifier onto the deployed ledger's legacy field. */
+export function emailTransportLedgerIdentifier(messageId: string | null): Record<string, string | null> {
+  return { resend_id: messageId };
+}
+
+/** Synthesizes the canonical terminal transport shape when `send` throws. */
+export function failedEmailTransportResult(): EmailSendResult {
+  return {
+    outcome: { ok: false, resendId: null, httpStatus: 0, providerError: "provider_transport_threw", aborted: false },
+    providerResponse: { exception: true },
+  };
+}
+
+export interface EmailSendOutcomeProjection {
+  skipReason: EmailSendSkipReason | null;
+  timelineStatus: "sent" | "skipped" | "delivery_delayed" | "failed";
+  ledgerStatus: "sent" | "skipped" | "failed";
+  sentAtEligible: boolean;
+  lastErrorCode: string | null;
+}
+
+/** One truth projection for every Node email ledger, timeline and caller. */
+export function classifyEmailSendOutcome(outcome: EmailSendOutcomeLike): EmailSendOutcomeProjection {
+  const skipReason = outcome.skipReason
+    ?? (outcome.adminDisabled ? "admin_disabled" : null)
+    ?? (outcome.suppressed === "drop" ? "egress_suppressed" : null);
+  if (skipReason) {
+    return {
+      skipReason,
+      timelineStatus: "skipped",
+      ledgerStatus: "skipped",
+      sentAtEligible: false,
+      lastErrorCode: skipReason,
+    };
+  }
+  // `ok` deliberately remains the transport-acceptance contract. In particular,
+  // this wave does not turn a historical 2xx-without-id answer into a retry.
+  if (outcome.ok) {
+    return {
+      skipReason: null,
+      timelineStatus: "sent",
+      ledgerStatus: "sent",
+      sentAtEligible: true,
+      lastErrorCode: null,
+    };
+  }
+  if (outcome.aborted) {
+    return {
+      skipReason: null,
+      timelineStatus: "delivery_delayed",
+      ledgerStatus: "failed",
+      sentAtEligible: false,
+      lastErrorCode: "provider_request_aborted",
+    };
+  }
+  return {
+    skipReason: null,
+    timelineStatus: "failed",
+    ledgerStatus: "failed",
+    sentAtEligible: false,
+    lastErrorCode: normalizeEmailFailureCode(outcome.providerError),
+  };
+}
+
+/** Adds a provider-neutral skip reason without changing ordinary wire shapes. */
+export function withEmailSendSkipReason<T extends EmailSendOutcomeLike>(outcome: T): T {
+  const skipReason = classifyEmailSendOutcome(outcome).skipReason;
+  return skipReason ? { ...outcome, skipReason } : outcome;
+}
+
+function normalizeEmailFailureCode(value: string | null): string {
+  if (!value) return "provider_send_failed";
+  const normalized = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 80);
+  return normalized || "provider_send_failed";
+}
+
+export interface EmailTransport {
+  /** Stable provider tag for ledgers/observability (e.g. "mailProvider", "in-memory"). */
+  readonly providerKind: string;
+  send(message: EmailMessage): Promise<EmailSendResult>;
+}
+
+export interface InMemoryEmailTransport extends EmailTransport {
+  /** Every message handed to send(), in order — for tests and dry runs. */
+  readonly sent: ReadonlyArray<EmailMessage>;
+}
+
+/**
+ * Reference capture transport: captures sends in memory and never makes a
+ * network call. Proves the seam is real — a port wired to this sends email with
+ * no HTTP client — and doubles as the substitute an OSS fork starts from
+ * before writing its own SES/SMTP adapter.
+ */
+export function createInMemoryEmailTransport(opts?: { idPrefix?: string }): InMemoryEmailTransport {
+  const sent: EmailMessage[] = [];
+  const prefix = opts?.idPrefix ?? "in-memory";
+  return admitPolicyEnforcedEmailTransport({
+    providerKind: "in-memory",
+    sent,
+    async send(message) {
+      sent.push(message);
+      const id = `${prefix}-${sent.length}`;
+      return {
+        outcome: { ok: true, resendId: id, httpStatus: 200, providerError: null, aborted: false },
+        providerResponse: { id },
+      };
+    },
+  });
+}

package/src/communications/errors.ts

@@ -0,0 +1,34 @@
+export class CommunicationRecipientNotFoundError extends Error {
+  constructor(message = "Communication recipient not found") {
+    super(message);
+    this.name = "CommunicationRecipientNotFoundError";
+  }
+}
+
+export class CommunicationTemplateNotFoundError extends Error {
+  constructor(message = "Communication template not found") {
+    super(message);
+    this.name = "CommunicationTemplateNotFoundError";
+  }
+}
+
+export class CommunicationConflictError extends Error {
+  constructor(message = "Communication request conflicts with current state") {
+    super(message);
+    this.name = "CommunicationConflictError";
+  }
+}
+
+export class CommunicationValidationError extends Error {
+  constructor(message = "Communication request is invalid") {
+    super(message);
+    this.name = "CommunicationValidationError";
+  }
+}
+
+export class CommunicationUnavailableError extends Error {
+  constructor(message = "Communication capability is unavailable") {
+    super(message);
+    this.name = "CommunicationUnavailableError";
+  }
+}