@runeditrun/rer 0.0.0-stage → 0.1.1

package/modules/mail/src/adapters/resend/README.md

@@ -0,0 +1,120 @@
+# Resend outbound adapter
+
+`sendResend(config, message, dependencies = {})` exports the portable, single
+submission adapter from `index.mjs`. Use the mail facade for ordinary sends and
+unsubscribe assembly. Direct calls validate configuration and the message through
+the real core helpers before any request. No SDK, Node API or build is required.
+
+The adapter submits JSON to `https://api.resend.com/emails` using `POST` and
+`Authorization: Bearer <apiKey>`. Envelope display names, `to`, `cc`, `bcc`, subject,
+text/HTML, `reply_to` and validated custom/thread headers are preserved. Names with
+mailbox delimiters are quoted. Omitted text allows Resend's HTML-to-text generation;
+an explicit empty text string disables that generation. At most 50 `to` recipients
+are accepted. [Send API](https://resend.com/docs/api-reference/emails/send-email)
+
+Attachments carry the original filename, Base64-encoded bytes and `content_type`.
+An inline attachment requires `contentId`; this becomes `content_id`. With no
+explicit disposition, a supplied content ID selects inline delivery. Without an
+ID the attachment is ordinary. Explicit `disposition: 'attachment'` together with
+an ID is rejected as `unsupported_resend_attachment_disposition`: Resend has no
+independent send disposition field. No remote attachment URLs are fetched.
+[Wire schema](https://github.com/resend/resend-openapi/blob/main/resend.yaml)
+and [inline images](https://resend.com/docs/dashboard/emails/embed-inline-images)
+
+## Outbound size budget
+
+Resend documents a **40 MB total email limit, including attachments after Base64
+encoding**. This adapter treats MB as decimal (40,000,000 bytes) and enforces a
+conservative local budget before making any request.
+[Provider attachment limitations](https://resend.com/docs/dashboard/emails/attachments#attachment-limitations)
+
+- The projected email starts with a 1,000,000-byte reserve for provider-added
+  envelope, MIME boundaries, headers and signatures. Each text/HTML or attachment
+  part adds 2,048 bytes. Metadata (sender, all `to`/`cc`/`bcc`, reply address,
+  subject, header names/values, filenames, content types and content IDs) costs
+  six times its UTF-8 byte length plus 128 bytes per string, covering encoding and
+  folding. An HTML-only request also reserves an equivalent generated text part.
+- Each attachment costs `4 * ceil(rawByteLength / 3)` Base64 bytes, plus two bytes
+  per 76-character MIME line. The aggregate includes every attachment, including
+  inline and empty attachments; there is no separate per-file allowance.
+- Text and HTML cost the larger of folded Base64 and conservative quoted-printable
+  encoding. The latter counts printable ASCII other than `=` as one byte, CR/LF
+  as two each, and other UTF-8 bytes as three; all spaces/tabs are counted as
+  encoded. It reserves three bytes per 73 encoded bytes for soft line breaks.
+- The projected JSON request must fit 39,000,000 UTF-8 bytes. It counts JSON
+  escapes (including lone surrogates), Base64 padding, 1,024 bytes of fixed
+  syntax, 64 extra bytes per metadata string and 128 per attachment. After
+  serialization, the actual request is independently checked against the same
+  39,000,000-byte ceiling before fetch.
+
+The checks are incremental and do not serialize metadata, allocate UTF-8 copies,
+map recipient/attachment arrays or read attachment content to estimate size. All
+attachments pass the aggregate check before the first Base64 encoding. The normal
+facade still validates and snapshots the caller's input as documented; these
+limits bound outbound serialization, not caller-owned input allocation.
+
+Exceeding either budget throws the public redacted `MailValidationError` with
+code `resend_message_too_large`, from both direct adapter and facade calls. No
+fetch, outbox write, retry, truncation or alternate send occurs. This is invalid
+input, not an uncertain submission. Bounds are inclusive; additional metadata or
+a second alternative reduces the permitted body/attachment size. These local
+estimates deliberately reject some requests below the provider maximum; the
+provider remains responsible for validating its final generated MIME message.
+
+SendGrid-specific `customArgs`, `asmGroupId` and `subscriptionTracking` are
+unsupported and rejected. A remaining `unsubscribe` property is rejected with
+`unsubscribe_requires_facade`; the facade must first assemble List-Unsubscribe
+headers and remove the request property. The adapter also refuses custom email
+headers named `Idempotency-Key` or `Resend-Idempotency-Key`, avoiding a second source
+of correlation/suppression policy. The caller's `deliveryId` is never inserted as
+a provider receipt.
+
+## Idempotency and outcomes
+
+`deliveryId` supplies the exact HTTP `Idempotency-Key`. This adapter accepts 1–256
+printable ASCII characters with no leading/trailing whitespace, so Fetch cannot
+silently alter the key. It does not hash or truncate unsupported keys. Applications
+must namespace their keys and retain the immutable payload for a send command.
+Resend retains keys for 24 hours: repeating the same request in that window yields
+the original response without another send. After expiry, reuse can send again;
+this is not indefinite duplicate suppression. A different payload under the same
+key produces HTTP 409 `invalid_idempotent_request`; an unfinished concurrent request
+produces 409 `concurrent_idempotent_requests`.
+[Provider idempotency contract](https://resend.com/docs/dashboard/emails/idempotency-keys)
+
+- HTTP 200 with a nonempty, control-free, bounded JSON `id` returns `accepted` and
+  that actual ID. Missing/malformed IDs, malformed/oversized JSON, response stream
+  failure and unexpected success statuses return `uncertain` with a null ID.
+- 429 returns `rate_limited`; 408, redirects, server errors and transport failures
+  return `uncertain`. Other ordinary 4xx statuses return `rejected`.
+- A recognized payload conflict returns `rejected`/`idempotency_conflict` for this
+  attempt. It does not establish whether the original request was accepted.
+  A concurrent conflict returns `uncertain`/`idempotency_in_progress`. Unknown or
+  malformed 409 responses are conservatively `uncertain`.
+
+There are no retries or alternate providers/outboxes. Core transport forces manual
+redirects and a 15-second request timeout. Structured response reads additionally
+stop at 64 KiB or 15 seconds and cancel unfinished streams. Diagnostics are fixed
+codes; response/error bodies and credentials are never returned or logged. HTTP
+acceptance is not delivery, inbox receipt, or proof of delivered header/DKIM
+coverage. Applications own durable policy and reconciliation.
+
+## Verification
+
+Run from the Base root:
+
+```sh
+node --test modules/mail/tests/resend/*.test.mjs
+node --check modules/mail/src/adapters/resend/index.mjs
+node --check modules/mail/src/adapters/resend/serialize.mjs
+node --check modules/mail/src/adapters/resend/response.mjs
+node --check modules/mail/src/adapters/resend/size.mjs
+```
+
+Fixtures live only in `modules/mail/tests/resend`; they inspect real Web Request
+bytes and Response streams. Size boundaries run in the adapter unit suite;
+`tests/runtime/workerd.test.mjs` checks a binary attachment through the facade
+and adapters, and `tests/assembly/workerd.test.mjs` checks the doctor sender chain.
+These checks establish local protocol behavior, not live-provider delivery.
+No provider credentials or live mail are used by these unit tests. Official
+references were inspected on 6 October 2026.

package/modules/mail/src/adapters/resend/index.mjs

@@ -0,0 +1,22 @@
+import { fail } from '../../core/errors.mjs';
+import { validateConfig } from '../../core/validation.mjs';
+import { requestProvider } from '../../core/transport.mjs';
+import { serializeResendMessage } from './serialize.mjs';
+import { resendResult } from './response.mjs';
+
+/** One submission. Acceptance is not mailbox delivery; callers own reconciliation. */
+export async function sendResend(config, message, dependencies = {}) {
+  validateConfig(config, dependencies);
+  if (config.provider !== 'resend') fail('invalid_provider');
+  const body = serializeResendMessage(message);
+  const response = await requestProvider('https://api.resend.com/emails', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      'Content-Type': 'application/json',
+      'Idempotency-Key': message.deliveryId,
+    },
+    body,
+  }, dependencies);
+  return resendResult(response);
+}

package/modules/mail/src/adapters/resend/response.mjs

@@ -0,0 +1,54 @@
+import { classifyHttpStatus, safeProviderMessageId, sendResult } from '../../core/transport.mjs';
+
+// Only bounded structured responses are inspected. Body text never becomes diagnostics.
+async function readObject(response) {
+  let reader;
+  let timer;
+  try {
+    reader = response.body?.getReader();
+    if (!reader) return null;
+    const expired = new Promise(resolve => { timer = setTimeout(() => resolve(null), 15_000); });
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    let text = '';
+    let size = 0;
+    while (true) {
+      const chunk = await Promise.race([reader.read(), expired]);
+      if (!chunk) return null;
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 65_536) return null;
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    const data = JSON.parse(text + decoder.decode());
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
+  } catch { return null; }
+  finally {
+    clearTimeout(timer);
+    // Cancellation itself can fail or stall on a broken stream; never wait for it.
+    if (reader) void reader.cancel().catch(() => {});
+  }
+}
+
+export async function resendResult(response) {
+  if (!response) return sendResult('resend', 'uncertain', null, 'transport_error');
+  if (response.status === 409) {
+    const data = await readObject(response);
+    if (data?.name === 'invalid_idempotent_request') return sendResult('resend', 'rejected', null, 'idempotency_conflict');
+    if (data?.name === 'concurrent_idempotent_requests') return sendResult('resend', 'uncertain', null, 'idempotency_in_progress');
+    return sendResult('resend', 'uncertain', null, 'idempotency_unknown_conflict');
+  }
+  const status = classifyHttpStatus(response.status);
+  if (status) {
+    if (response.body) void response.body.cancel().catch(() => {});
+    return sendResult('resend', status, null, status === 'rate_limited' ? 'rate_limited' : status === 'rejected' ? 'provider_rejected' : 'unexpected_response');
+  }
+  // POST /emails documents HTTP 200 with an id, not bare HTTP success.
+  if (response.status !== 200) {
+    if (response.body) void response.body.cancel().catch(() => {});
+    return sendResult('resend', 'uncertain', null, 'unexpected_response');
+  }
+  const data = await readObject(response);
+  const id = safeProviderMessageId(data?.id);
+  if (!id || id !== data.id || 'error' in data || 'name' in data) return sendResult('resend', 'uncertain', null, 'invalid_provider_response');
+  return sendResult('resend', 'accepted', id);
+}

package/modules/mail/src/adapters/resend/serialize.mjs

@@ -0,0 +1,46 @@
+import { fail } from '../../core/errors.mjs';
+import { encodeBase64, parseAddress, validateMessage } from '../../core/validation.mjs';
+import { assertResendMessageSize, assertResendRequestSize } from './size.mjs';
+
+function mailbox(value) {
+  const { email, name } = parseAddress(value);
+  // Quote names containing mailbox delimiters so one address remains one address.
+  return name ? `${/[(),:;@\[\]]/.test(name) ? `"${name}"` : name} <${email}>` : email;
+}
+
+export function serializeResendMessage(message) {
+  if (message && Object.hasOwn(message, 'unsubscribe')) fail('unsubscribe_requires_facade');
+  validateMessage(message, 'resend');
+  // Preserve the exact key across Fetch's header normalization. No hashing/truncation.
+  if (!/^[\x20-\x7e]{1,256}$/.test(message.deliveryId) || message.deliveryId.trim() !== message.deliveryId) fail('invalid_resend_idempotency_key');
+  if (message.to.length > 50) fail('resend_recipient_limit');
+  assertResendMessageSize(message);
+  for (const name in message.headers) {
+    if (!Object.hasOwn(message.headers, name)) continue;
+    if (['idempotency-key', 'resend-idempotency-key'].includes(name.toLowerCase())) fail('reserved_resend_header');
+  }
+  const attachments = message.attachments?.map(attachment => {
+    // Resend derives inline disposition from content_id; no independent disposition exists.
+    if (attachment.disposition === 'attachment' && attachment.contentId !== undefined) fail('unsupported_resend_attachment_disposition');
+    return {
+      filename: attachment.filename,
+      content: encodeBase64(attachment.content),
+      content_type: attachment.contentType,
+      ...(attachment.contentId === undefined ? {} : { content_id: attachment.contentId }),
+    };
+  });
+  const body = JSON.stringify({
+    from: mailbox(message.from),
+    to: message.to.map(mailbox),
+    subject: message.subject,
+    ...(message.text === undefined ? {} : { text: message.text }),
+    ...(message.html === undefined ? {} : { html: message.html }),
+    ...(message.cc === undefined ? {} : { cc: message.cc.map(mailbox) }),
+    ...(message.bcc === undefined ? {} : { bcc: message.bcc.map(mailbox) }),
+    ...(message.replyTo === undefined ? {} : { reply_to: mailbox(message.replyTo) }),
+    ...(message.headers === undefined ? {} : { headers: message.headers }),
+    ...(attachments === undefined ? {} : { attachments }),
+  });
+  assertResendRequestSize(body);
+  return body;
+}

package/modules/mail/src/adapters/resend/size.mjs

@@ -0,0 +1,99 @@
+import { fail } from '../../core/errors.mjs';
+
+// Resend documents 40 MB including Base64 attachments. Use decimal MB and leave
+// 1 MB for provider-added MIME/envelope/signature data; see the adapter README.
+export const MAX_RESEND_EMAIL_BYTES = 40_000_000;
+export const MAX_RESEND_REQUEST_BYTES = 39_000_000;
+const ENVELOPE_RESERVE = MAX_RESEND_EMAIL_BYTES - MAX_RESEND_REQUEST_BYTES;
+const PART_RESERVE = 2048;
+const tooLarge = () => fail('resend_message_too_large');
+const base64Size = bytes => 4 * Math.ceil(bytes / 3);
+const foldedBase64Size = bytes => {
+  const encoded = base64Size(bytes);
+  return encoded + 2 * Math.ceil(encoded / 76);
+};
+
+// Count without TextEncoder/JSON copies, including JSON escapes and lone UTF-16
+// surrogates. Stop once even the source string exceeds the remaining budget.
+function stringSize(value, limit) {
+  if (value.length > limit) tooLarge();
+  let utf8 = 0;
+  let json = 2; // quotes
+  let quotedPrintable = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    let bytes = code < 0x80 ? 1 : code < 0x800 ? 2 : 3;
+    let unpaired = code >= 0xd800 && code <= 0xdfff;
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) { bytes = 4; unpaired = false; i++; }
+    }
+    utf8 += bytes;
+    json += unpaired || code < 0x20 && ![8, 9, 10, 12, 13].includes(code) ? 6
+      : code === 34 || code === 92 || code < 0x20 ? 2 : bytes;
+    // Encode all whitespace conservatively, including trailing spaces/tabs.
+    quotedPrintable += code >= 33 && code <= 126 && code !== 61 ? 1
+      : code === 10 || code === 13 ? 2 : 3 * bytes;
+    if (json > limit) tooLarge();
+  }
+  return { utf8, json, quotedPrintable };
+}
+
+/** Preflight validated inputs before mailbox arrays, Base64 or JSON allocation. */
+export function assertResendMessageSize(message) {
+  let request = 1024; // fixed JSON field names, delimiters and optional containers
+  let email = ENVELOPE_RESERVE;
+  function add(requestBytes, emailBytes) {
+    request += requestBytes;
+    email += emailBytes;
+    if (request > MAX_RESEND_REQUEST_BYTES || email > MAX_RESEND_EMAIL_BYTES) tooLarge();
+  }
+  function metadata(value) {
+    const size = stringSize(value, MAX_RESEND_REQUEST_BYTES - request);
+    // Covers MIME header encoding/folding plus address quoting/normalization.
+    add(size.json + 64, 6 * size.utf8 + 128);
+  }
+  metadata(message.from);
+  metadata(message.subject);
+  if (message.replyTo !== undefined) metadata(message.replyTo);
+  for (const field of ['to', 'cc', 'bcc']) {
+    for (const value of message[field] ?? []) metadata(value);
+  }
+  for (const name in message.headers) {
+    if (!Object.hasOwn(message.headers, name)) continue;
+    metadata(name);
+    metadata(message.headers[name]);
+  }
+  for (const field of ['text', 'html']) {
+    if (message[field] === undefined) continue;
+    const size = stringSize(message[field], MAX_RESEND_REQUEST_BYTES - request);
+    // Reserve the larger of Base64 and conservative quoted-printable transfer
+    // encodings, including line folding, without assuming Resend's MIME choice.
+    const quotedPrintable = size.quotedPrintable + 3 * Math.ceil(size.quotedPrintable / 73);
+    const part = PART_RESERVE + Math.max(foldedBase64Size(size.utf8), quotedPrintable);
+    // HTML-only requests permit provider-generated plain text. Budget another
+    // part; explicit text (including an empty string) suppresses that generation.
+    add(size.json, part * (field === 'html' && message.text === undefined ? 2 : 1));
+  }
+  for (const attachment of message.attachments ?? []) {
+    // Charge the complete aggregate before any attachment bytes are read.
+    add(base64Size(attachment.content.byteLength) + 128,
+      PART_RESERVE + foldedBase64Size(attachment.content.byteLength));
+    metadata(attachment.filename);
+    metadata(attachment.contentType);
+    if (attachment.contentId !== undefined) metadata(attachment.contentId);
+  }
+}
+
+/** Final actual UTF-8 request bound, independently of the preflight estimate. */
+export function assertResendRequestSize(body) {
+  // A valid JSON string has no unescaped lone surrogates. Counting code points
+  // avoids allocating a second body-sized Uint8Array just to measure the request.
+  if (body.length > MAX_RESEND_REQUEST_BYTES) tooLarge();
+  let bytes = 0;
+  for (const character of body) {
+    const code = character.codePointAt(0);
+    bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+    if (bytes > MAX_RESEND_REQUEST_BYTES) tooLarge();
+  }
+}

package/modules/mail/src/adapters/sendgrid/README.md

@@ -0,0 +1,75 @@
+# SendGrid outgoing adapter
+
+`index.mjs` exports the portable ESM functions
+`sendSendGrid(config, message, dependencies = {})` and
+`serializeSendGridMessage(message)`. Both accept the frozen IF-056-MAIL-v1
+message shape. The serializer validates and returns deterministic JSON request
+bytes without effects; the sender validates config and message independently
+and makes one POST to `https://api.sendgrid.com/v3/mail/send` with Bearer API-key
+authentication. Config must name `provider: 'sendgrid'`, an explicit mode, and
+`apiKey`. Remote sending remains remote in test/development modes. There is no
+endpoint override, provider fallback, outbox selection or automatic retry.
+
+The facade must call the actual `applyUnsubscribeHeaders` implementation before
+this adapter. That assembler consumes `unsubscribe` and returns a new message
+with the real headers. Direct callers must call the assembler themselves, or
+supply their already-validated headers without an `unsubscribe` request. The
+adapter rejects every unconsumed `unsubscribe` request, including one accompanied
+by matching-looking headers, with `unsubscribe_requires_facade`. It validates
+header syntax/reserved names and preserves headers; it does not certify the
+semantics or delivered/DKIM coverage of caller-supplied unsubscribe headers.
+
+The wire preserves To/Cc/Bcc display names, plain/HTML alternatives, reply address,
+thread and custom headers, binary attachments, disposition and content IDs.
+Attachments use base64 generated from `Uint8Array`; callers never supply base64.
+`rer_delivery_id` always carries the caller's delivery ID. Custom arguments retain
+the original reserved-name and 10,000-byte UTF-8 JSON limit. Positive safe-integer
+ASM group IDs and optional boolean subscription tracking are supported. Omitted
+subscription tracking remains omitted. Open, click and Google Analytics tracking
+are explicitly disabled. Subscription tracking may append provider content;
+its selection is not proof of delivered unsubscribe headers.
+
+Shared core validation rejects unknown fields, header/address injection and
+unsupported shapes. SendGrid additionally rejects empty subjects, explicitly
+empty content parts/attachments, duplicate recipients, non-ASCII sender mailbox
+addresses, and more than 1,000 total To/Cc/Bcc recipients. Omit unused content
+parts. Local resource ceilings are 1,000 attachments, 1,000 header entries (custom arguments retain their 10,000-byte limit), 1,000,000 header key/value code units, and request JSON strictly below
+30,000,000 UTF-8 bytes. Body and base64-size checks run before encoding attachments;
+final serialized bytes are checked too. The wire ceiling does not establish that
+the provider-generated MIME is below its separate 30 MB message limit. Oversize
+or unsupported requests fail before fetch with fixed `MailValidationError` codes;
+no values appear in diagnostics.
+
+The shared transport enforces a 15-second deadline, abort signal and manual
+redirect handling. Only HTTP 202 reports `accepted`; its real, bounded
+`X-Message-Id` is retained or explicitly null. That is submission acceptance,
+not mailbox receipt. HTTP 429 is `rate_limited`; other 4xx except 408 are
+`rejected`. Network loss, deadline expiry, redirects, 408, 5xx and unexpected
+non-202 responses are `uncertain`. Results never expose provider bodies/errors.
+Correlation is not duplicate suppression: reconcile an uncertain submission
+before deciding whether to submit again.
+
+## Verification
+
+From Base root:
+
+```sh
+node --test modules/mail/tests/sendgrid/*.test.mjs modules/mail/tests/core/*.test.mjs
+```
+
+Tests include complete wire conformance, all response classes, no retry/forwarding,
+redaction, nullable receipts, direct-call validation, binary round trips, exact
+custom-argument limit, a real 15-second deadline, and isolated ESM execution with
+Web APIs only (no Buffer/process/require). They use injected test-only responses;
+no live provider API is called. `tests/sendgrid/conformance.mjs` exports
+`runSendGridConformance()` for reuse inside workerd, and
+`tests/sendgrid/worker.mjs` is its Worker entry. The isolated harness can run it with
+`createWorker('tests/sendgrid/worker.mjs', ['tests/sendgrid/conformance.mjs',
+'src/adapters/sendgrid/index.mjs'])`, then dispatch a fetch and dispose the worker.
+`tests/assembly/workerd.test.mjs` exercises the complete facade inside actual
+workerd, including unsubscribe assembly and the doctor sender chain. Hosted send/receive proof remains pending.
+
+Provider references checked 6 October 2026:
+[Mail Send](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send),
+[limits](https://www.twilio.com/docs/sendgrid/api-reference/mail-send), and
+[X-Message-ID](https://www.twilio.com/docs/sendgrid/glossary/x-message-id).

package/modules/mail/src/adapters/sendgrid/index.mjs

@@ -0,0 +1,35 @@
+import { validateConfig } from '../../core/validation.mjs';
+import { fail, MailValidationError } from '../../core/errors.mjs';
+import { requestProvider, classifyHttpStatus, sendResult, safeProviderMessageId } from '../../core/transport.mjs';
+import { serializeSendGridMessage } from './serialize.mjs';
+
+export { serializeSendGridMessage } from './serialize.mjs';
+
+/** One submission; acceptance is not mailbox delivery or duplicate suppression. */
+export async function sendSendGrid(config, message, dependencies = {}) {
+  let body;
+  let apiKey;
+  try {
+    validateConfig(config, dependencies);
+    if (config.provider !== 'sendgrid') fail('sendgrid_provider_required');
+    body = serializeSendGridMessage(message);
+    apiKey = config.apiKey;
+  } catch (error) {
+    if (error instanceof MailValidationError) throw error;
+    fail('invalid_mail_input');
+  }
+  const response = await requestProvider('https://api.sendgrid.com/v3/mail/send', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+    body,
+  }, dependencies);
+  if (response === null) return sendResult('sendgrid', 'uncertain', null, 'transport_uncertain');
+  // Provider bodies may contain secrets or personal information. Never read them.
+  if (response.status === 202) {
+    return sendResult('sendgrid', 'accepted', safeProviderMessageId(response.headers.get('x-message-id')));
+  }
+  const status = classifyHttpStatus(response.status) ?? 'uncertain';
+  return sendResult('sendgrid', status, null, {
+    rejected: 'provider_rejected', rate_limited: 'provider_rate_limited', uncertain: 'provider_uncertain',
+  }[status]);
+}

package/modules/mail/src/adapters/sendgrid/serialize.mjs

@@ -0,0 +1,104 @@
+import { validateMessage, parseAddress, encodeBase64 } from '../../core/validation.mjs';
+import { fail, MailValidationError } from '../../core/errors.mjs';
+
+// Local allocation/wire ceilings, not a promise that provider-generated MIME fits.
+const maxWireBytes = 30_000_000;
+const encoder = new TextEncoder();
+
+function preflight(message) {
+  if (!message || typeof message !== 'object') fail('invalid_message');
+  let recipients = 0;
+  for (const field of ['to', 'cc', 'bcc']) {
+    if (Array.isArray(message[field])) recipients += message[field].length;
+  }
+  if (recipients > 1000) fail('sendgrid_too_many_recipients');
+  let bytes = 0;
+  for (const field of ['text', 'html']) {
+    const value = message[field];
+    if (typeof value === 'string') {
+      if (value.length >= maxWireBytes) fail('sendgrid_message_too_large');
+      bytes += encoder.encode(value).byteLength;
+    }
+  }
+  if (Array.isArray(message.attachments)) {
+    if (message.attachments.length > 1000) fail('sendgrid_too_many_attachments');
+    for (const attachment of message.attachments) {
+      if (attachment?.content instanceof Uint8Array) bytes += 4 * Math.ceil(attachment.content.byteLength / 3);
+      if (bytes >= maxWireBytes) fail('sendgrid_message_too_large');
+    }
+  }
+  if (bytes >= maxWireBytes) fail('sendgrid_message_too_large');
+  // Bound records before the shared validator serializes custom arguments.
+  for (const field of ['headers', 'customArgs']) {
+    const record = message[field];
+    if (record && typeof record === 'object') {
+      const keys = Reflect.ownKeys(record);
+      if (keys.length > (field === 'customArgs' ? 10_000 : 1000)) fail('sendgrid_metadata_too_large');
+      let size = 0;
+      for (const key of keys) {
+        const value = record[key];
+        size += typeof key === 'string' ? key.length : 0;
+        size += typeof value === 'string' ? value.length : 0;
+        if (size > (field === 'customArgs' ? 10_000 : 1_000_000)) fail('sendgrid_metadata_too_large');
+      }
+    }
+  }
+}
+
+/** Validated deterministic request bytes, without any provider or outbox effect. */
+export function serializeSendGridMessage(message) {
+  try {
+    preflight(message);
+    validateMessage(message, 'sendgrid');
+    // Only the real unsubscribe assembler consumes this feature request.
+    if (message.unsubscribe !== undefined) fail('unsubscribe_requires_facade');
+    if (!message.subject.length) fail('sendgrid_subject_required');
+    const from = parseAddress(message.from);
+    if (/[^\x00-\x7f]/.test(from.email)) fail('sendgrid_ascii_sender_required');
+    const personalization = { to: message.to.map(parseAddress) };
+    if (message.cc?.length) personalization.cc = message.cc.map(parseAddress);
+    if (message.bcc?.length) personalization.bcc = message.bcc.map(parseAddress);
+    const recipients = new Set();
+    for (const list of Object.values(personalization)) {
+      for (const { email } of list) {
+        const key = email.toLowerCase();
+        if (recipients.has(key)) fail('sendgrid_duplicate_recipient');
+        recipients.add(key);
+      }
+    }
+    const content = [];
+    for (const [field, type] of [['text', 'text/plain'], ['html', 'text/html']]) {
+      if (message[field] !== undefined) {
+        if (!message[field].length) fail('sendgrid_empty_content');
+        content.push({ type, value: message[field] });
+      }
+    }
+    const attachments = message.attachments?.map(attachment => {
+      if (!attachment.content.byteLength) fail('sendgrid_empty_attachment');
+      return {
+        content: encodeBase64(attachment.content), type: attachment.contentType,
+        filename: attachment.filename, disposition: attachment.disposition ?? 'attachment',
+        ...(attachment.contentId === undefined ? {} : { content_id: attachment.contentId }),
+      };
+    });
+    const body = JSON.stringify({
+      personalizations: [personalization], from, subject: message.subject, content,
+      ...(message.replyTo === undefined ? {} : { reply_to: parseAddress(message.replyTo) }),
+      // The facade always supplies a headers object; an empty one is the same request as none.
+      ...(message.headers === undefined || !Reflect.ownKeys(message.headers).length ? {} : { headers: message.headers }),
+      ...(attachments?.length ? { attachments } : {}),
+      custom_args: { ...message.customArgs, rer_delivery_id: message.deliveryId },
+      ...(message.asmGroupId === undefined ? {} : { asm: { group_id: message.asmGroupId } }),
+      tracking_settings: {
+        click_tracking: { enable: false, enable_text: false }, open_tracking: { enable: false },
+        ganalytics: { enable: false },
+        ...(message.subscriptionTracking === undefined ? {} : { subscription_tracking: { enable: message.subscriptionTracking } }),
+      },
+    });
+    if (encoder.encode(body).byteLength >= maxWireBytes) fail('sendgrid_message_too_large');
+    return body;
+  } catch (error) {
+    if (error instanceof MailValidationError) throw error;
+    fail('invalid_mail_input');
+  }
+}

package/modules/mail/src/core/errors.mjs

@@ -0,0 +1,9 @@
+/** Input values never appear in validation diagnostics. */
+export class MailValidationError extends Error {
+  constructor(code = 'invalid_mail_input') {
+    super('Mail input is invalid; check the error code and module contract.');
+    this.name = 'MailValidationError';
+    this.code = typeof code === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(code) ? code : 'invalid_mail_input';
+  }
+}
+export function fail(code) { throw new MailValidationError(code); }

package/modules/mail/src/core/transport.mjs

@@ -0,0 +1,33 @@
+import { validateSendResult } from './validation.mjs';
+
+/** One bounded request. Fetch exceptions never escape with credential/body text. */
+export async function requestProvider(url, init, dependencies = {}) {
+  const timeout = dependencies.timeoutMilliseconds ?? 15_000;
+  let timer;
+  try {
+    const deadline = new Promise(resolve => { timer = setTimeout(() => resolve(null), timeout); });
+    return await Promise.race([
+      Promise.resolve().then(() => (dependencies.fetch ?? globalThis.fetch)(url, {
+        ...init, redirect: 'manual', signal: AbortSignal.timeout(timeout),
+      })).then(response => response instanceof Response ? response : null, () => null),
+      deadline,
+    ]);
+  } catch { return null; }
+  finally { clearTimeout(timer); }
+}
+
+export function classifyHttpStatus(status) {
+  if (status === 429) return 'rate_limited';
+  if (status >= 400 && status < 500 && status !== 408) return 'rejected';
+  if (status >= 200 && status < 300) return null;
+  return 'uncertain';
+}
+
+export function safeProviderMessageId(value) {
+  return typeof value === 'string' && value.trim() && value.length <= 1024 && !/[\x00-\x1f\x7f]/.test(value) ? value.trim() : null;
+}
+export function sendResult(provider, status, providerMessageId = null, code, recipientResults) {
+  return validateSendResult({ provider, status, providerMessageId,
+    ...(code === undefined ? {} : { code }), ...(recipientResults === undefined ? {} : { recipientResults }),
+  }, provider);
+}