@k2b/cloud 0.27.0 → 0.28.0

package/src/services/notifications/email-mail.ts

@@ -0,0 +1,101 @@
+import { domainToASCII } from "node:url";
+import type { ZodError } from "zod";
+import { type MailMessage, MailMessageSchema, type MailRecord } from "../../contracts/outgoing-mail";
+import { messageRecord, outgoingMailMessages } from "../outgoing-mail/messages";
+import { sendMail } from "../outgoing-mail/send";
+import { OutgoingMailError } from "../outgoing-mail/store";
+import { prepareNotificationEmail } from "./email-frame";
+
+export const notificationMailError = (error: unknown): Error & { code: string; retryable: boolean } => {
+  const code = error instanceof OutgoingMailError ? error.code : "mail_unavailable";
+  return Object.assign(new Error(error instanceof Error ? error.message : "Outgoing mail is unavailable."), {
+    code,
+    retryable: ["mail_unavailable", "backlog_full", "quota_exceeded", "attachment_storage_full"].includes(code),
+  });
+};
+
+export const normalizeNotificationMail = (to: string, subject: string) => {
+  const separator = to.lastIndexOf("@");
+  const domain = separator < 0 ? "" : to.slice(separator + 1);
+  // URL conversion can discard invalid address characters; leave those for validation.
+  const ascii = domain && !/[^\p{L}\p{N}\p{M}.-]/u.test(domain) ? domainToASCII(domain) : "";
+  return {
+    to: [ascii ? `${to.slice(0, separator + 1)}${ascii}` : to],
+    subject: subject
+      .replace(/[\r\n]+/g, " ")
+      .replace(/\0/g, "")
+      .trim()
+      .slice(0, 998),
+  };
+};
+
+export const notificationMailValidationError = (error: ZodError) =>
+  new OutgoingMailError(
+    "bad_input",
+    `Invalid notification email: ${error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`,
+    400,
+  );
+
+const notificationMailMessage = async (
+  to: string,
+  subject: string,
+  body: { content?: string; rawHtml?: string },
+  key?: string,
+): Promise<MailMessage> => {
+  const parsed = MailMessageSchema.safeParse({
+    ...normalizeNotificationMail(to, subject),
+    ...(await prepareNotificationEmail(body)),
+    ...(key ? { key } : {}),
+  });
+  if (!parsed.success) throw notificationMailValidationError(parsed.error);
+  return parsed.data;
+};
+
+export const sendNotificationMail = async (
+  to: string,
+  subject: string,
+  body: { content?: string; rawHtml?: string },
+  key?: string,
+  signal?: AbortSignal,
+): Promise<MailRecord> => {
+  try {
+    return await sendMail("core", await notificationMailMessage(to, subject, body, key), signal, { trustedHtml: true });
+  } catch (error) {
+    throw notificationMailError(error);
+  }
+};
+
+export const notificationMailOutcome = async (record: MailRecord) => {
+  const row = await outgoingMailMessages.read(record.id, "core").catch(() => undefined);
+  const status = row?.status ?? record.status;
+  const errorCode = row?.error_code ?? (record.error ? "smtp_failed" : null);
+  const errorMessage = row?.error_message ?? row?.smtp_response ?? record.error ?? null;
+  if (status === "sent" || status === "bounced") return { status: "delivered" as const, outgoingMailId: record.id };
+  if (status === "failed" || status === "cancelled") {
+    throw Object.assign(new Error(errorMessage ?? `Outgoing mail ${status}.`), {
+      code: errorCode ?? "smtp_failed",
+      retryable: false,
+      outgoingMailId: record.id,
+    });
+  }
+  const next = row?.next_attempt_at ? new Date(row.next_attempt_at).getTime() - Date.now() : 60_000;
+  // Keep polling within the notification retry interval bounds.
+  const retryAfterMs = Number.isFinite(next) ? Math.min(5 * 60_000, Math.max(2_000, next)) : 60_000;
+  return { status: "pending" as const, outgoingMailId: record.id, retryAfterMs, errorMessage };
+};
+
+export const notificationMailOutcomeById = async (id: string) => {
+  const row = await outgoingMailMessages.read(id, "core").catch((error: unknown) => {
+    throw notificationMailError(error);
+  });
+  if (!row) {
+    // Retention may remove a settled mail before notification recovery. Its
+    // stored identity must never turn that recovery into another SMTP send.
+    throw Object.assign(new Error("Outgoing mail record is no longer available."), {
+      code: "smtp_failed",
+      retryable: false,
+      outgoingMailId: id,
+    });
+  }
+  return notificationMailOutcome(messageRecord(row));
+};

package/src/services/notifications/index.ts

@@ -4,7 +4,7 @@ import type { BoundNotificationDefinition, NotificationRecipientKind, Notificati
 import type { PaginationParams } from "../../contracts/shared";
 import { logger } from "../logging";
 import { escapeLikePattern } from "../postgres";
-import { sendEmail } from "./email";
+import { notificationMailOutcome, sendNotificationMail } from "./email-mail";
 import "./browser";
 import { notificationObservability } from "./observability";
 import { sendTypedNotification, type TypedNotificationSendResult } from "./platform";
@@ -107,6 +107,26 @@ type DbNotificationRow = {
   sent_by_name: string | null;
 };
 
+type LegacyMailRow = { id: string; type: NotificationType; recipient: string; subject: string; content: string; mail_generation: number };
+
+const deliverLegacyMail = async (row: LegacyMailRow, body: { content?: string; rawHtml?: string }) => {
+  const key = `notification-message:${row.id}${row.mail_generation ? `:${row.mail_generation}` : ""}`;
+  try {
+    const record = await sendNotificationMail(row.recipient, row.subject, body, key);
+    await sql`UPDATE notifications.messages SET outgoing_mail_id = ${record.id}::uuid, sent_at = NULL, error = NULL
+      WHERE id = ${row.id}::uuid AND mail_generation = ${row.mail_generation}`;
+    const outcome = await notificationMailOutcome(record);
+    if (outcome.status === "pending") return "pending" as const;
+    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL
+      WHERE id = ${row.id}::uuid AND mail_generation = ${row.mail_generation}`;
+    return "sent" as const;
+  } catch (error) {
+    await sql`UPDATE notifications.messages SET sent_at = NULL, error = ${error instanceof Error ? error.message : String(error)}
+      WHERE id = ${row.id}::uuid AND mail_generation = ${row.mail_generation}`;
+    throw error;
+  }
+};
+
 /**
  * Send a notification. Persists to DB, attempts delivery (if autoSend=true), updates sent_at/error.
  */
@@ -130,15 +150,11 @@ const sendLegacy = async (params: SendNotificationParams): Promise<SendNotificat
 
   // Attempt delivery
   try {
-    if (type === "email") {
-      await sendEmail(recipient, subject, { content, rawHtml });
-    }
-    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}`;
-    return { id, status: "sent" };
+    const status = await deliverLegacyMail({ id, type, recipient, subject, content: dbContent, mail_generation: 0 }, { content, rawHtml });
+    return { id, status };
   } catch (e) {
     const error = e instanceof Error ? e.message : String(e);
     log.error("Failed to send", { type, recipient, error });
-    await sql`UPDATE notifications.messages SET error = ${error} WHERE id = ${id}`;
     return { id, status: "error", error };
   }
 };
@@ -482,23 +498,26 @@ export const getById = async (id: string): Promise<NotificationMessage | null> =
  * Resend a notification (retry delivery).
  */
 export const resend = async (id: string): Promise<{ ok: true } | { ok: false; code: "not_found" | "delivery_failed"; error: string }> => {
-  const notification = await getById(id);
-  if (!notification) {
-    return { ok: false, code: "not_found", error: "Notification not found" };
-  }
-
+  const notification = await sql.begin(async (tx): Promise<(LegacyMailRow & { current_mail_status: string | null }) | undefined> => {
+    const [row] = await tx<(LegacyMailRow & { outgoing_mail_id: string | null; current_mail_status: string | null })[]>`
+      SELECT m.*, mail.status AS current_mail_status FROM notifications.messages m
+      LEFT JOIN outgoing_mail.messages mail ON mail.id = m.outgoing_mail_id
+      WHERE m.id = ${id}::uuid FOR UPDATE OF m
+    `;
+    if (!row || row.current_mail_status === "queued" || row.current_mail_status === "sending" || !row.outgoing_mail_id) return row;
+    const [updated] = await tx<LegacyMailRow[]>`
+      UPDATE notifications.messages SET mail_generation = mail_generation + 1, outgoing_mail_id = NULL, sent_at = NULL, error = NULL
+      WHERE id = ${id}::uuid RETURNING *
+    `;
+    return updated ? { ...updated, current_mail_status: null } : undefined;
+  });
+  if (!notification) return { ok: false, code: "not_found", error: "Notification not found" };
+  if (["queued", "sending"].includes(notification.current_mail_status ?? "")) return { ok: true };
   try {
-    if (notification.type === "email") {
-      await sendEmail(notification.recipient, notification.subject, {
-        rawHtml: notification.content,
-      });
-    }
-    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}`;
+    await deliverLegacyMail(notification, { rawHtml: notification.content });
     return { ok: true };
   } catch (e) {
-    const error = e instanceof Error ? e.message : String(e);
-    await sql`UPDATE notifications.messages SET error = ${error} WHERE id = ${id}`;
-    return { ok: false, code: "delivery_failed", error };
+    return { ok: false, code: "delivery_failed", error: e instanceof Error ? e.message : String(e) };
   }
 };
 
@@ -535,7 +554,9 @@ export const update = async (
       subject = COALESCE(${data.subject ?? null}, subject),
       content = COALESCE(${data.content ?? null}, content),
       recipient = COALESCE(${data.recipient ?? null}, recipient),
-      error = CASE WHEN ${clearError} THEN NULL ELSE error END
+      error = CASE WHEN ${clearError} THEN NULL ELSE error END,
+      mail_generation = CASE WHEN ${clearError} THEN mail_generation + 1 ELSE mail_generation END,
+      outgoing_mail_id = CASE WHEN ${clearError} THEN NULL ELSE outgoing_mail_id END
     WHERE id = ${id}
   `;
 
@@ -548,7 +569,7 @@ export const update = async (
 export const getPendingSystemCount = async (): Promise<number> => {
   const rows = await sql`
     SELECT COUNT(*)::int as count FROM notifications.messages
-    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL
+    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL AND outgoing_mail_id IS NULL
   `;
   return rows[0]?.count ?? 0;
 };
@@ -563,10 +584,10 @@ export const sendAllPendingSystem = async (): Promise<{
   errors: { id: string; recipient: string; error: string }[];
 }> => {
   // Get all pending system notifications
-  const rows = await sql`
-    SELECT id, type, recipient, subject, content
+  const rows = await sql<LegacyMailRow[]>`
+    SELECT id, type, recipient, subject, content, mail_generation
     FROM notifications.messages
-    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL
+    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL AND outgoing_mail_id IS NULL
     ORDER BY created_at ASC
   `;
 
@@ -575,21 +596,13 @@ export const sendAllPendingSystem = async (): Promise<{
   const errors: { id: string; recipient: string; error: string }[] = [];
 
   for (const row of rows) {
-    const id = row.id as string;
-    const type = row.type as NotificationType;
-    const recipient = row.recipient as string;
-    const subject = row.subject as string;
-    const content = row.content as string;
+    const { id, recipient, content } = row;
 
     try {
-      if (type === "email") {
-        await sendEmail(recipient, subject, { rawHtml: content });
-      }
-      await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}`;
+      if ((await deliverLegacyMail(row, { rawHtml: content })) === "pending") continue;
       sent++;
     } catch (e) {
       const error = e instanceof Error ? e.message : String(e);
-      await sql`UPDATE notifications.messages SET error = ${error} WHERE id = ${id}`;
       failed++;
       errors.push({ id, recipient, error });
     }

package/src/services/notifications/observability.ts

@@ -1,4 +1,5 @@
 import { type SQL, sql } from "bun";
+import type { MailStatus } from "../../contracts/outgoing-mail";
 import type { NotificationDeliveryStatus } from "../../contracts/user-notifications";
 import { escapeLikePattern, toPgTextArray } from "../postgres";
 
@@ -20,6 +21,8 @@ export type NotificationDeliveryObservabilityItem = {
   required: boolean;
   routePriority: number | null;
   status: NotificationDeliveryStatus;
+  outgoingMailId: string | null;
+  outgoingMailStatus: MailStatus | null;
   attemptCount: number;
   errorCode: string | null;
   errorMessage: string | null;
@@ -79,6 +82,8 @@ type DeliveryRow = {
   required: boolean;
   route_priority: number | null;
   status: NotificationDeliveryStatus;
+  outgoing_mail_id: string | null;
+  outgoing_mail_status: MailStatus | null;
   attempt_count: number;
   error_code: string | null;
   error_message: string | null;
@@ -168,11 +173,12 @@ const listDeliveries = async (input: {
         COALESCE(NULLIF(u.display_name, ''), NULLIF(u.uid, ''), e.recipient_email, e.recipient_key) AS recipient_label,
         COALESCE(NULLIF(u.mail, ''), NULLIF(u.uid, ''), e.recipient_email, e.recipient_key) AS recipient_reference,
         d.channel, d.destination_label, d.required, d.route_priority, d.status,
-        d.attempt_count, d.error_code, d.error_message, d.created_at, d.updated_at, d.delivered_at
+        d.outgoing_mail_id, mail.status AS outgoing_mail_status, d.attempt_count, d.error_code, d.error_message, d.created_at, d.updated_at, d.delivered_at
       FROM notifications.deliveries d
       JOIN notifications.events e ON e.id = d.event_id
       JOIN notifications.definitions n ON n.id = e.definition_id
       LEFT JOIN auth.users u ON u.id = e.recipient_user_id
+      LEFT JOIN outgoing_mail.messages mail ON mail.id = d.outgoing_mail_id
       WHERE ${where}
       ORDER BY d.created_at DESC, d.id DESC
       LIMIT ${perPage} OFFSET ${offset}
@@ -196,6 +202,8 @@ const listDeliveries = async (input: {
       required: row.required,
       routePriority: row.route_priority,
       status: row.status,
+      outgoingMailId: row.outgoing_mail_id,
+      outgoingMailStatus: row.outgoing_mail_status,
       attemptCount: row.attempt_count,
       errorCode: row.error_code,
       errorMessage: row.error_message,

package/src/services/notifications/platform.ts

@@ -407,7 +407,7 @@ export const sendTypedNotification = async <
   if (persisted.prepared) {
     for (const deliveryId of persisted.requiredIds) {
       const result = await processNotificationDelivery(deliveryId);
-      if (result.status === "retry") await enqueueNotificationDelivery(deliveryId, result.retryAfterMs);
+      if (result.status === "retry" || result.status === "pending") await enqueueNotificationDelivery(deliveryId, result.retryAfterMs);
       if (result.activatedIds?.length) await enqueueNotificationDeliveries(result.activatedIds);
     }
     await enqueueNotificationDeliveries(persisted.pendingIds);

package/src/services/notifications/runtime.ts

@@ -3,7 +3,7 @@ import { lazySync } from "../../_internal/process-sync";
 import { logger, trace } from "../logging";
 import { createRuntimeLifecycle, createRuntimeTaskTracker, stopRuntimeJobs } from "../runtime-lifecycle";
 
-import { processNotificationDelivery, recoverNotificationDeliveries } from "./dispatcher";
+import { processNotificationDelivery, reconcileNotificationMessages, recoverNotificationDeliveries } from "./dispatcher";
 
 type DeliveryMessage = { deliveryId: string };
 
@@ -58,10 +58,10 @@ const handleDelivery = async (context: JobContext<DeliveryMessage>): Promise<voi
       spanKey: trace.syncSpanKey("job", "cloud-notification-deliveries", context.jobId),
       attributes: { "cloud.notification.delivery_id": context.input.deliveryId },
     },
-    () => processNotificationDelivery(context.input.deliveryId),
+    () => processNotificationDelivery(context.input.deliveryId, context.signal),
   );
   if (result.activatedIds?.length) await enqueueNotificationDeliveries(result.activatedIds);
-  if (result.status === "retry") context.resubmit({ delayMs: result.retryAfterMs });
+  if (result.status === "retry" || result.status === "pending") context.resubmit({ delayMs: result.retryAfterMs });
 };
 
 type RuntimeOptions = { concurrency?: number; recoveryIntervalMs?: number };
@@ -79,6 +79,12 @@ const recover = (): Promise<void> => {
       } catch (error) {
         log.error("Delivery recovery failed", { error: error instanceof Error ? error.message : String(error) });
       }
+      // Message history must never hold back delivery recovery.
+      try {
+        await reconcileNotificationMessages();
+      } catch (error) {
+        log.error("Notification message reconciliation failed", { error: error instanceof Error ? error.message : String(error) });
+      }
     }) ?? Promise.resolve()
   ).finally(() => {
     recovery = undefined;

package/src/services/outgoing-mail/admin.ts

@@ -0,0 +1,84 @@
+import { sql } from "bun";
+import {
+  type AdminMailFilter,
+  type AdminMailRecord,
+  AdminMailRecordSchema,
+  type MailPage,
+  type MailPageParams,
+} from "../../contracts/outgoing-mail";
+import { audit } from "../audit";
+import { cleanupMailAttachments, publishMailSettled } from "./dispatcher";
+import { adminMessageRecord, type MessageRow, outgoingMailMessages } from "./messages";
+import { type MailAuditContext, OutgoingMailError } from "./store";
+
+const get = async (id: string): Promise<AdminMailRecord> => {
+  const record = await outgoingMailMessages.metadata(id);
+  if (!record) throw new OutgoingMailError("message_unknown", "Outgoing mail message does not exist.", 404);
+  return record;
+};
+const cancel = async (id: string, context: MailAuditContext): Promise<AdminMailRecord> => {
+  const row = await sql.begin(async (tx) => {
+    const [row] = await tx<MessageRow[]>`UPDATE outgoing_mail.messages SET status = 'cancelled', error_code = 'cancelled_by_admin',
+      error_message = 'Cancelled by an administrator.', next_attempt_at = NULL, updated_at = now() WHERE id = ${id}::uuid AND status = 'queued'
+      RETURNING *, created_at::text AS cursor_created_at`;
+    if (!row) {
+      if (!(await outgoingMailMessages.read(id, undefined, tx)))
+        throw new OutgoingMailError("message_unknown", "Outgoing mail message does not exist.", 404);
+      throw new OutgoingMailError("message_not_queued", "Only queued outgoing mail can be cancelled.", 409);
+    }
+    await audit.record(
+      {
+        ...context,
+        action: "outgoing_mail.message.cancel",
+        outcome: "allowed",
+        target: { type: "outgoing_mail_message", id },
+        metadata: { appId: row.app_id, profile: row.profile_key },
+      },
+      tx,
+    );
+    return row;
+  });
+  await cleanupMailAttachments(id).catch(() => {});
+  await publishMailSettled(id).catch(() => {});
+  return adminMessageRecord(row);
+};
+export const outgoingMailLog = {
+  get,
+  cancel,
+  async cancelBatch(batchId: string, context: MailAuditContext): Promise<{ batchId: string; cancelled: number }> {
+    const cancelled = await sql.begin(async (tx) => {
+      const apps = await tx<{ app_id: string }[]>`SELECT DISTINCT app_id FROM outgoing_mail.messages WHERE batch_id = ${batchId}::uuid`;
+      if (!apps.length) throw new OutgoingMailError("batch_unknown", "Outgoing mail batch does not exist.", 404);
+      const rows = await tx<{ id: string }[]>`UPDATE outgoing_mail.messages SET status = 'cancelled', error_code = 'cancelled_by_admin',
+        error_message = 'Cancelled by an administrator.', next_attempt_at = NULL, updated_at = now()
+        WHERE batch_id = ${batchId}::uuid AND status = 'queued' RETURNING id`;
+      await audit.record(
+        {
+          ...context,
+          action: "outgoing_mail.batch.cancel",
+          outcome: "allowed",
+          target: { type: "outgoing_mail_batch", id: batchId },
+          metadata: { appIds: apps.map((row) => row.app_id), count: rows.length },
+        },
+        tx,
+      );
+      return rows;
+    });
+    for (const row of cancelled) {
+      await cleanupMailAttachments(row.id).catch(() => {});
+      await publishMailSettled(row.id).catch(() => {});
+    }
+    return { batchId, cancelled: cancelled.length };
+  },
+  content: outgoingMailMessages.content,
+  list: async (filter: AdminMailFilter, page: MailPageParams): Promise<MailPage<AdminMailRecord>> => {
+    const result = await outgoingMailMessages.list(filter, page, true);
+    return {
+      ...result,
+      items: result.items.map((item) => {
+        // The metadata mapper deliberately omits content; validate its public boundary.
+        return AdminMailRecordSchema.parse(item);
+      }),
+    };
+  },
+};

package/src/services/outgoing-mail/attachments.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { type ObjectRef, StoreFullError } from "@k2b/sync";
+import type { MailAttachment, MailRecord } from "../../contracts/outgoing-mail";
+import { OutgoingMailError } from "./store";
+import { mailAttachments } from "./sync";
+
+export type UploadedAttachments = { metadata: MailRecord["attachments"]; refs: ObjectRef[] };
+export const MAIL_ATTACHMENT_UPLOAD_MS = 60_000;
+export const cancelMailStreams = (attachments: unknown = []): void => {
+  if (!Array.isArray(attachments)) return;
+  for (const attachment of attachments) {
+    if (
+      attachment &&
+      typeof attachment === "object" &&
+      "content" in attachment &&
+      attachment.content instanceof ReadableStream &&
+      !attachment.content.locked
+    )
+      void attachment.content.cancel().catch(() => {});
+  }
+};
+export const deleteMailObjects = async (refs: readonly ObjectRef[]): Promise<void> => {
+  // Sequential deletion bounds load even for a large attachment collection.
+  for (const ref of refs) await mailAttachments().delete({ tenantId: ref.tenantId, key: ref.key });
+};
+const contentStream = (content: MailAttachment["content"]): ReadableStream<Uint8Array> => {
+  if (content instanceof ReadableStream) return content;
+  if (content instanceof Blob) return content.stream();
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(content);
+      controller.close();
+    },
+  });
+};
+export const uploadMailAttachments = async (
+  id: string,
+  attachments: readonly MailAttachment[],
+  limit: number,
+  uploadDeadline?: number,
+): Promise<UploadedAttachments> => {
+  const result: UploadedAttachments = { metadata: [], refs: [] };
+  let total = 0;
+  const controller = new AbortController();
+  // The caller's signal cancels the wait only. All attachments share one bounded upload.
+  if (uploadDeadline !== undefined && uploadDeadline <= Date.now() && attachments.length) {
+    cancelMailStreams(attachments);
+    throw new OutgoingMailError("mail_unavailable", "Attachment upload timed out.");
+  }
+  const timer = setTimeout(
+    () => controller.abort(new Error("Attachment upload timed out")),
+    uploadDeadline === undefined ? MAIL_ATTACHMENT_UPLOAD_MS : Math.max(0, uploadDeadline - Date.now()),
+  );
+  try {
+    for (const [index, attachment] of attachments.entries()) {
+      const hash = createHash("sha256");
+      let size = 0;
+      let exceeded = false;
+      const key = `${id}-${index}`;
+      try {
+        const stream = contentStream(attachment.content).pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>({
+            transform(chunk, output) {
+              total += chunk.byteLength;
+              size += chunk.byteLength;
+              if (total > limit) {
+                exceeded = true;
+                throw new OutgoingMailError("attachments_too_large", "Attachments exceed the profile's total byte limit.");
+              }
+              hash.update(chunk);
+              output.enqueue(chunk);
+            },
+          }),
+          { signal: controller.signal },
+        );
+        const ref = await mailAttachments().put({ tenantId: id, key, body: stream, signal: controller.signal });
+        result.refs.push(ref);
+        result.metadata.push({ filename: attachment.filename, contentType: attachment.contentType, size, sha256: hash.digest("hex") });
+      } catch (error) {
+        // A failed put can have written chunks before the final metadata was published.
+        await mailAttachments()
+          .delete({ tenantId: id, key })
+          .catch(() => {});
+        if (exceeded) throw new OutgoingMailError("attachments_too_large", "Attachments exceed the profile's total byte limit.");
+        if (
+          error instanceof StoreFullError ||
+          (error instanceof Error &&
+            /maximum bytes|maximum storage|insufficient (?:storage|resources)|storage resources|store.*full|resource limits exceeded/i.test(
+              error.message,
+            ))
+        )
+          throw new OutgoingMailError("attachment_storage_full", "Outgoing mail attachment storage is full.");
+        throw error;
+      }
+    }
+    return result;
+  } catch (error) {
+    await deleteMailObjects(result.refs).catch(() => {});
+    cancelMailStreams(attachments);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+};
+
+/** Verify before SMTP DATA; open a second, verified stream for nodemailer. */
+export const verifyMailAttachment = async (
+  ref: ObjectRef,
+  metadata: MailRecord["attachments"][number],
+  signal?: AbortSignal,
+): Promise<void> => {
+  const object = await mailAttachments().get(ref, { signal });
+  if (!object) throw new OutgoingMailError("attachment_lost", "An outgoing mail attachment is missing or changed.");
+  const reader = object.body.getReader();
+  const hash = createHash("sha256");
+  let size = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > metadata.size) throw new Error("Attachment size mismatch");
+      hash.update(chunk.value);
+    }
+    if (size !== metadata.size || hash.digest("hex") !== metadata.sha256) throw new Error("Attachment digest mismatch");
+  } catch (error) {
+    if (signal?.aborted || (error instanceof Error && /stalled|timeout|timed out|connection/i.test(error.message)))
+      throw new Error("Attachment verification was interrupted.");
+    throw new OutgoingMailError("attachment_lost", "An outgoing mail attachment is missing or changed.");
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+};

package/src/services/outgoing-mail/bulk.ts

@@ -0,0 +1,11 @@
+export const MAIL_RECOVERY_MS = 30_000;
+export const mailSlotMs = (pacePerMinute: number): number => 60_000 / pacePerMinute;
+export const mailBacklogFull = (queued: number, added: number, pacePerMinute: number): boolean =>
+  added > 0 && queued + added > pacePerMinute * 1440;
+export const mailBatchId = (proposed: string, rows: readonly ({ batch_id: string | null } | undefined)[]): string => {
+  const previous = rows[0]?.batch_id;
+  return previous && rows.every((row) => row?.batch_id === previous) ? previous : proposed;
+};
+// Later submissions join a coalesced continuation, so long backoffs must not hide fresh mail.
+export const mailNextDrainDelay = (now: number, slot: number, due: number): number =>
+  Math.min(MAIL_RECOVERY_MS, Math.max(0, Math.max(slot, due) - now));