@ultimat3/mail 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -35,6 +35,20 @@
   result is re-checked by `assertHeaderSafe`; a throw or a malformed result is
   `X_MAIL_TRANSFORM_FAILED` and nothing is sent. None installed ⇒ the same object, byte-identical.
 
+- **`send()` enqueues through `jobsFacade().enqueue(sendMailJob, message)`, never `jobDriver().enqueue`**
+  (`As of 2026-10-02`). The driver call published on the pool, autocommitted, so a handler that
+  rolled back after `send()` still mailed — and under `{ retry }` each re-run could mail again.
+  Through the facade an ambient transaction STAGES the row and the relay publishes it after COMMIT.
+  `send-outbox.job.test.ts` proves a rollback delivers nothing, on the memory pair and on Postgres.
+- **One recipient rule, inline and queued** (`As of 2026-10-02`). `addressRefusal`
+  (`envelope-address.ts`) is `envelopeAddress`'s rule without the throw; `renderMessage` applies it
+  to `to`/`cc`/`bcc`/`replyTo` after the header gate, and `mailMessageSchema` refines with it. It was
+  `t.email` on the queue and nothing inline, so `Jane Doe <jane@x.test>` answered `queued: true` and
+  the worker's parse refused the row. `unsubscribeUrl` is `t.url` on both paths for the same reason.
+- `X_MAIL_HEADER_INVALID` carries `meta.reason` (`line-break` | `non-ascii`) with a cause per
+  reason; the non-ASCII mailbox refusal was raised with the line-break cause until 2026-10-02.
+  `Reply-To` takes the `address` mode in `mime.ts` (encoded phrase, refused non-ASCII mailbox), and
+  an ASCII phrase holding an RFC 5322 special other than `.` is quoted (`"Doe, Jane"`).
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineMail` file
   imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
   every access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.
@@ -163,11 +177,12 @@
   data reaches `Subject`, and a break there injects headers. Refuse it, never strip it.
 - Every ENVELOPE address is checked the same way and separately (`X_MAIL_ADDRESS_INVALID`,
   `envelope-address.ts`, called by `smtpDeliver`). Two wire formats, one gate each: `bcc` is not a
-  header, so the header gate never sees it, and on the inline send path no schema does either — a
-  `bcc` of `ops@x.test\r\nRCPT TO:<evil@y.test>` relayed mail over the app's own authenticated
-  connection. The refused set is control characters plus `<` and `>`; a space is deliberately
-  allowed (quoted local-parts). Non-ASCII in the MAILBOX is refused too, and by this package:
-  SMTPUTF8 (RFC 6531) is what makes a UTF-8 addr-spec legal and `smtp-client.ts` negotiates none.
+  header, so the header gate never sees it, and on the inline send path no schema did either until
+  `renderMessage` took `addressRefusal` (2026-10-02) — a `bcc` of
+  `ops@x.test\r\nRCPT TO:<evil@y.test>` relayed mail over the app's own authenticated connection.
+  The refused set is control characters plus `<` and `>`; a space is deliberately allowed (quoted
+  local-parts). Non-ASCII in the MAILBOX is refused too, and by this package: SMTPUTF8 (RFC 6531)
+  is what makes a UTF-8 addr-spec legal and `smtp-client.ts` negotiates none.
 
 ## Commands
 

package/README.md

@@ -20,8 +20,10 @@ export const receiptMail = defineMail({
 await send(receiptMail, { name: user.name, url }, { to: user.email, locale: ctx.locale });
 ```
 
-`send` validates `data` through the mail's schema, renders, then enqueues `mail.send`. It
-delivers inline only when `{ sync: true }` is passed or no job driver is configured.
+`send` validates `data` through the mail's schema, renders, then enqueues `mail.send` through the
+jobs facade — inside a transaction the job is STAGED on it, so a handler that rolls back after
+sending mails nobody. It delivers inline only when `{ sync: true }` is passed or no job driver is
+configured.
 
 ### The outbound transform
 
@@ -58,6 +60,8 @@ setMailTransform(async (rendered, meta) =>
 | Every colour is a token | `MAIL_TOKENS` in `layout.ts` holds light + dark hexes; templates never see a hex |
 | Every date takes an IANA zone | `options.tz`, else `ctx.tz`, else `UTC` |
 | No CR/LF in a header-bound field | checked in `renderMessage` and again in `sendMailJob`, so every driver refuses the same message (`X_MAIL_HEADER_INVALID`). `mime.ts` keeps its own gate for the headers the SMTP transport mints itself |
+| One recipient rule on both paths | `to`, `cc`, `bcc` and `replyTo` are checked in `renderMessage` by the rule the SMTP envelope applies (`addressRefusal`), and the queue schema asks the same — so a display-form `Jane Doe <jane@x.test>` is accepted everywhere, and a control character or a non-ASCII mailbox is `X_MAIL_ADDRESS_INVALID` at the `send()` call site on every driver, never `queued: true` and then a worker's parse failure. `unsubscribeUrl` is `t.url` on both paths for the same reason |
+| Address headers carry 7-bit phrases | `From`, `To`, `Cc` and `Reply-To` encode a non-ASCII display name as an RFC 2047 word and quote an ASCII one holding a special (`Doe, Jane` → `"Doe, Jane"`), so the comma cannot split the list. `List-Unsubscribe` carries the url as the WHATWG serialiser writes it — punycode host, percent-encoded path and query |
 | `unsubscribeUrl` is one-click, and one-click is the supported path | it emits `List-Unsubscribe: <url>` plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058), and the footer links the SAME url. Make that url one page that answers both: `GET` renders a confirm button and never unsubscribes (scanners prefetch), and `POST` — the mail client's one-click, or the button's own form — runs the action: `defineRoute({ render: 'ssr', …, post: 'unsubscribe' })` (`@ultimat3/render`) binds it, with the url's query (`?t=<token>`) merged into the input. `unsubscribeOneClick: false` drops the `-Post` line for a url that still cannot take a POST; it is the fallback, not the path |
 | Sending is a job | `retry: { attempts: 5, backoff: 'exponential' }`, idempotency key `mail:<mailId>:<hash(recipients + rendered)>` — 128 bits, ASCII, under Resend's 256-character limit at any recipient count — or `(mailId, your key)` when you pass one (digested if it is not a short ASCII token) — a caller's key is scoped to its mail so two templates cannot dedupe each other away |
 
@@ -149,7 +153,7 @@ Translating them = shipping `mail.*` keys in an app catalog. Never edit a templa
 | `X_MAIL_DRIVER_UNAVAILABLE` | `setMailDriver(createMemoryDriver())` at boot — a wiring bug |
 | `X_MAIL_CREDENTIAL_MISSING` | set `SMTP_URL` (or `RESEND_API_KEY`) and `MAIL_FROM` in the deployment — an operations one |
 | `X_MAIL_HEADER_INVALID` | strip CR/LF from the interpolated value before it reaches a header |
-| `X_MAIL_ADDRESS_INVALID` | pass a bare `addr-spec` — an envelope address may hold no control character and no `<`/`>` |
+| `X_MAIL_ADDRESS_INVALID` | a recipient may hold no control character, its mailbox no `<`/`>` and no non-ASCII byte (`meta.reason`); `Jane Doe <jane@x.test>` is fine |
 | `X_MAIL_TRANSFORM_FAILED` | the `setMailTransform` hook threw or returned no `{ subject, html, text }` — fix the hook; the mail was not sent |
 | `X_MAIL_SEND_FAILED` | the `cause` names the stage, the provider's status and whether a retry can help — and so does `error.retry`, which is what `sendMailJob` acts on: `terminal` dead-letters a 550 or a rejected credential at attempt 1 instead of sending it four more times |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,10 +32,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/jobs": "22.15.0",
-    "@ultimat3/schema": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/jobs": "24.0.0",
+    "@ultimat3/schema": "24.0.0",
+    "@ultimat3/time": "24.0.0"
   }
 }

package/src/driver-smtp.ts

@@ -84,11 +84,29 @@ function parseSmtpUrl(raw: string): SmtpUrl {
     port: url.port === '' ? (tls ? IMPLICIT_TLS_PORT : SUBMISSION_PORT) : Number(url.port),
     tls,
     // Credentials are percent-encoded in a URL; a password with `@` or `/` is otherwise unusable.
-    ...(url.username === '' ? {} : { user: decodeURIComponent(url.username) }),
-    ...(url.password === '' ? {} : { password: decodeURIComponent(url.password) }),
+    ...(url.username === '' ? {} : { user: decodedCredential('user', url.username) }),
+    ...(url.password === '' ? {} : { password: decodedCredential('password', url.password) }),
   };
 }
 
+/**
+ * `decodeURIComponent` throws a bare `URIError` for a `%` that starts no escape, which escaped
+ * `createSmtpDriver` as the one SMTP_URL mistake that was not a config error. The value is a
+ * credential, so neither the cause nor the fix ever carries it.
+ */
+function decodedCredential(part: 'user' | 'password', raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new ConfigInvalidError({
+      cause: `the SMTP_URL ${part} holds a "%" that starts no percent-escape, so it cannot be decoded`,
+      // `prompt`, so the credential reaches neither shell history nor this message.
+      fix: `percent-encode the ${part} and put the output in SMTP_URL: bun -e 'console.log(encodeURIComponent(prompt("${part}:") ?? ""))'`,
+      meta: { part },
+    });
+  }
+}
+
 /**
  * `poolSize: 0` is the one config mistake this driver could not report: the limiter would park
  * every send on a slot that is never handed out, with no deadline on the wait, so the job would

package/src/driver.ts

@@ -62,7 +62,7 @@ export function messageHeaders(message: MailMessage): Readonly<Record<string, st
   const headers: Record<string, string> = { 'Auto-Submitted': 'auto-generated' };
   if (message.replyTo !== undefined) headers['Reply-To'] = message.replyTo;
   if (message.unsubscribeUrl !== undefined) {
-    headers['List-Unsubscribe'] = `<${message.unsubscribeUrl}>`;
+    headers['List-Unsubscribe'] = `<${unsubscribeTarget(message.unsubscribeUrl)}>`;
     if (message.unsubscribeOneClick !== false) {
       headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
     }
@@ -70,6 +70,22 @@ export function messageHeaders(message: MailMessage): Readonly<Record<string, st
   return headers;
 }
 
+/**
+ * The url as the WHATWG serialiser writes it: host as punycode, path, query and fragment
+ * percent-encoded — 7-bit, and with no bare `>` to close the angle bracket early. It went out as
+ * written, so a non-ASCII url was raw 8-bit octets in a header. A url holding a control character
+ * is copied through UNTOUCHED: the serialiser silently drops CR, LF and tab, and a header break is
+ * refused by the CR/LF gate, never stripped into a different url. `send()` and the queue schema
+ * refuse an unparseable url first; a hand-built one is copied through and stays the caller's.
+ */
+function unsubscribeTarget(url: string): string {
+  if (CONTROL.test(url)) return url;
+  return URL.parse(url)?.href ?? url;
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the control range IS the rule.
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
 /**
  * Every address the envelope is delivered to. `Bcc` is one of them and never a header —
  * an SMTP `RCPT TO` carries it, and putting it in the message would leak the blind list.
@@ -216,7 +232,7 @@ export function createLogDriver(logger = rootLogger): MailDriver {
 
 let ambient: MailDriver | undefined;
 
-/** Set once at boot from `app.config.ts`. One driver per process, like the job driver. */
+/** Set once at boot from the environment (`selectMailDriver`). One per process, like the job driver. */
 export function setMailDriver(driver: MailDriver): void {
   ambient = driver;
 }

package/src/envelope-address.ts

@@ -4,7 +4,7 @@
 // thing only — the RFC 5322 display form down to the mailbox `RCPT TO:` can carry, always after
 // the control-character check, never before it.
 
-import { addressInvalid, type EnvelopeAddressField } from './errors';
+import { type AddressRefusal, addressInvalid, type EnvelopeAddressField } from './errors';
 import { addressSpec, hasNonAsciiAddrSpec } from './mime';
 
 /**
@@ -39,29 +39,49 @@ function hasControlCharacter(address: string): boolean {
   return false;
 }
 
+/** What `isUnsafe` and the mailbox check say of a bare addr-spec — the half both gates share. */
+function specRefusal(spec: string): AddressRefusal | undefined {
+  if (isUnsafe(spec)) return 'injection';
+  // Two reasons, checked in this order: an injection is the dangerous one and an address carrying
+  // both should say so. The addr-spec, never the phrase — `mime.ts` has an RFC 2047 encoding for a
+  // display name and none for a mailbox.
+  return hasNonAsciiAddrSpec(spec) ? 'non-ascii' : undefined;
+}
+
 /** Throws `X_MAIL_ADDRESS_INVALID` before a single byte of the envelope is written. */
 export function assertEnvelopeAddress(field: EnvelopeAddressField, address: string): void {
-  if (isUnsafe(address)) throw addressInvalid(field, 'injection');
-  // Two reasons, two `meta.reason`s, checked in this order: an injection is the dangerous one and
-  // an address carrying both should say so. The addr-spec, never the phrase — `mime.ts` has an
-  // RFC 2047 encoding for a display name and none for a mailbox.
-  if (hasNonAsciiAddrSpec(address)) throw addressInvalid(field, 'non-ascii');
+  const refusal = specRefusal(address);
+  if (refusal !== undefined) throw addressInvalid(field, refusal);
 }
 
 /**
- * The addr-spec an envelope command may carry, from whatever form the caller wrote. `Jane Doe
- * <jane@x.test>` is the ordinary RFC 5322 display form — the `To:` header carries it verbatim and
- * the resend, memory and log drivers all accept it — but `RCPT TO:` takes a mailbox, so it is
- * stripped here and the gate above runs on what is left.
+ * Why `address` cannot be a recipient, or `undefined` when it can — `envelopeAddress`'s rule without
+ * the throw, so the queue schema (`job.ts`) and `renderMessage` (`mail.ts`) ask the SAME question
+ * the SMTP envelope does. It was `t.email` on the queue and nothing inline, so a display-form
+ * recipient was `queued: true` at `send()` and then refused by the worker's parse.
  *
  * The control-character half runs on the RAW value, BEFORE the strip, and the order is the whole
  * point: `ops@x.test\r\nRCPT TO:<attacker@evil.test>` strips down to a clean-looking mailbox that
  * every later check waves through, so a strip-then-check would have turned the injection into a
  * delivery to the attacker instead of a refusal.
  */
+export function addressRefusal(address: string): AddressRefusal | undefined {
+  return hasControlCharacter(address) ? 'injection' : specRefusal(addressSpec(address));
+}
+
+/** Throws `X_MAIL_ADDRESS_INVALID` for any address `addressRefusal` refuses. */
+export function assertRecipientAddress(field: EnvelopeAddressField, address: string): void {
+  const refusal = addressRefusal(address);
+  if (refusal !== undefined) throw addressInvalid(field, refusal);
+}
+
+/**
+ * The addr-spec an envelope command may carry, from whatever form the caller wrote. `Jane Doe
+ * <jane@x.test>` is the ordinary RFC 5322 display form — the `To:` header carries it verbatim and
+ * every driver accepts it — but `RCPT TO:` takes a mailbox, so it is stripped here once
+ * `addressRefusal` has passed the raw value.
+ */
 export function envelopeAddress(field: EnvelopeAddressField, address: string): string {
-  if (hasControlCharacter(address)) throw addressInvalid(field, 'injection');
-  const spec = addressSpec(address);
-  assertEnvelopeAddress(field, spec);
-  return spec;
+  assertRecipientAddress(field, address);
+  return addressSpec(address);
 }

package/src/errors.ts

@@ -185,19 +185,53 @@ export const mailCredentialMissing = (environment: Environment): MailError =>
     meta: { environment, missing: ['SMTP_URL', 'RESEND_API_KEY'] },
   });
 
+/**
+ * Why a header was refused. Two reasons, one code, as `AddressRefusal` is for the envelope: a
+ * non-ASCII MAILBOX in an address header was raised with the line-break cause, which named a
+ * character the value did not hold.
+ */
+export type HeaderRefusal = 'line-break' | 'non-ascii';
+
+/** The `send()` option each address header comes from; `From` is the transport's own config. */
+const ADDRESS_OPTION: ReadonlyMap<string, string> = new Map([
+  ['To', 'to'],
+  ['Cc', 'cc'],
+  ['Reply-To', 'replyTo'],
+]);
+
+/**
+ * The domain as punycode is the ASCII form; a non-ASCII LOCAL part has none and needs another
+ * mailbox. The example is fixed text — an address is recipient data, never echoed back.
+ */
+const nonAsciiFix = (name: string): string => {
+  const option = ADDRESS_OPTION.get(name);
+  return option === undefined
+    ? 'set mail.from in app.config.ts to an ASCII mailbox, e.g. no-reply@example.test'
+    : `pass the mailbox's ASCII form, the domain as punycode: send(mail, data, { ${option}: 'jose@xn--exmple-cua.test', locale })`;
+};
+
 /**
  * A CR or LF inside a header value ends the header early and lets whatever follows become new
  * headers — the recipient list, a forged `From`. Interpolated data reaches `Subject`, so this is
  * refused rather than stripped: silently rewriting a subject is its own surprise.
  */
-export const headerInvalid = (name: string, mailId: string): MailError =>
+export const headerInvalid = (
+  name: string,
+  mailId: string,
+  reason: HeaderRefusal = 'line-break',
+): MailError =>
   new MailError({
     code: 'X_MAIL_HEADER_INVALID',
-    cause: `the "${name}" header of mail "${mailId}" contains a CR or LF, which would inject headers`,
+    cause:
+      reason === 'line-break'
+        ? `the "${name}" header of mail "${mailId}" contains a CR or LF, which would inject headers`
+        : `the "${name}" header of mail "${mailId}" holds a non-ASCII byte in its mailbox, and this package negotiates no SMTPUTF8, so the address cannot be written as a header`,
     fix:
-      `strip line breaks from the value before it reaches the header: ` +
-      `t('mail.${mailId}.subject', { ...data, x: String(x).replace(/[\\r\\n]+/g, ' ') })`,
-    meta: { header: name, mailId },
+      reason === 'line-break'
+        ? `strip line breaks from the value before it reaches the header: ` +
+          `t('mail.${mailId}.subject', { ...data, x: String(x).replace(/[\\r\\n]+/g, ' ') })`
+        : nonAsciiFix(name),
+    meta: { header: name, mailId, reason },
   });
 
 /**

package/src/html.ts

@@ -1,19 +1,8 @@
-// Single responsibility: turning untrusted values into inert HTML. Mail bodies interpolate
-// user-supplied names, org names and URLs; an unescaped one is a phishing vector that also
-// renders in the recipient's client forever, so escaping lives in exactly one place.
+// Single responsibility: the mail-specific half of making untrusted values inert — which URLs a
+// link may carry and how a style attribute is written. The character escaping is core's
+// `escapeHtml`, the one table: an unescaped name in a mail is a phishing vector forever.
 
-const ESCAPES: Readonly<Record<string, string>> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#39;',
-};
-
-/** Escape text content AND attribute values — the same set covers both in mail. */
-export function escapeHtml(value: string): string {
-  return value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
-}
+import { escapeHtml } from '@ultimat3/core';
 
 const SAFE_PROTOCOLS: readonly string[] = ['http:', 'https:', 'mailto:'];
 

package/src/index.ts

@@ -1,12 +1,12 @@
 // Single responsibility: the public API of @ultimat3/mail. Explicit named exports only —
 // other packages call `defineMail`, `send` and the driver seam, and nothing else.
 
+export { escapeHtml } from '@ultimat3/core';
 /** Re-exported so a `defineMail` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
 export { blocks } from './blocks';
-
 export { MAIL_CATALOG, MAIL_CATALOG_LOCALE } from './catalog';
 export type {
   MailDriver,
@@ -61,8 +61,7 @@ export {
   transformFailed,
 } from './errors';
 export { assertHeaderSafe } from './header-safety';
-
-export { escapeHtml, safeUrl } from './html';
+export { safeUrl } from './html';
 
 export { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
 export { mailMessageSchema, sendMailJob } from './job';

package/src/job.ts

@@ -5,21 +5,33 @@
 import { type JobHandle, job } from '@ultimat3/jobs';
 import { type StandardSchemaV1, t } from '@ultimat3/schema';
 import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { addressRefusal } from './envelope-address';
 import { assertHeaderSafe } from './header-safety';
 import { mailIdempotencyKey } from './idempotency';
 
+/**
+ * A recipient by the rule the SMTP envelope applies (`addressRefusal`), never `t.email`: the
+ * inline path takes the RFC 5322 display form, so a stricter queue schema turned a `send()` that
+ * answered `queued: true` into a worker that refused the row it had just been handed.
+ */
+const mailAddress = t.refine(t.string, {
+  name: 'mail-address',
+  message: 'a mailbox or a display-form address, with no control character or non-ASCII mailbox',
+  check: (address) => addressRefusal(address) === undefined,
+});
+
 /** The queue payload is the already-rendered envelope: rendering happens once, at send time. */
 export const mailMessageSchema: StandardSchemaV1<unknown, MailMessage> = t.object({
   mailId: t.string,
-  to: t.array(t.email),
+  to: t.array(mailAddress),
   subject: t.string,
   html: t.string,
   text: t.string,
   locale: t.locale,
   tz: t.timezone,
-  replyTo: t.email.optional(),
-  cc: t.array(t.email).optional(),
-  bcc: t.array(t.email).optional(),
+  replyTo: mailAddress.optional(),
+  cc: t.array(mailAddress).optional(),
+  bcc: t.array(mailAddress).optional(),
   unsubscribeUrl: t.url.optional(),
   unsubscribeOneClick: t.boolean.optional(),
   idempotencyKey: t.string.optional(),

package/src/layout.ts

@@ -3,8 +3,9 @@
 // renderer, because email clients drop <style> and templates must never carry a raw hex.
 // Table-based and 600px wide: Outlook still renders with Word's HTML engine.
 
+import { escapeHtml } from '@ultimat3/core';
 import { mailLayoutDuplicate } from './errors';
-import { escapeHtml, safeUrl, styleAttr } from './html';
+import { safeUrl, styleAttr } from './html';
 
 export type ColorScheme = 'light' | 'dark';
 

package/src/mail.ts

@@ -4,10 +4,11 @@
 // piece of context that a background send cannot recover after the fact.
 
 import { assert, DEFAULT_TIME_ZONE, tryUseContext } from '@ultimat3/core';
-import { jobDriver } from '@ultimat3/jobs';
-import { parse, type StandardSchemaV1 } from '@ultimat3/schema';
+import { jobDriver, jobsFacade } from '@ultimat3/jobs';
+import { parse, type StandardSchemaV1, t } from '@ultimat3/schema';
 import type { MailTemplate } from './blocks';
-import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { envelopeRecipients, type MailMessage, mailDriver, type SendResult } from './driver';
+import { assertRecipientAddress } from './envelope-address';
 import { localeMissing, mailDuplicate, templateUnknown } from './errors';
 import { assertHeaderSafe } from './header-safety';
 import { mailIdempotencyKey } from './idempotency';
@@ -90,7 +91,9 @@ export function mailFor(id: string): AnyMailDefinition | undefined {
 }
 
 export function registeredMails(): readonly AnyMailDefinition[] {
-  return [...registry.values()].sort((a, b) => a.id.localeCompare(b.id));
+  // Through `registeredMailIds`, so the two views share ONE order: the code-unit sort. It was
+  // `localeCompare` here, which puts `welcome` before `Zeta` where the id list puts it after.
+  return registeredMailIds().flatMap((id) => registry.get(id) ?? []);
 }
 
 export function registeredMailIds(): readonly string[] {
@@ -123,6 +126,11 @@ export function renderMessage<I>(
   );
 
   const input = parse(mail.input, data, `${mail.id}.input`);
+  // The queue schema's own rule (`t.url`), so an unparseable url is refused here rather than
+  // delivered inline as `List-Unsubscribe: <not a url>` and refused by a worker when queued.
+  if (options.unsubscribeUrl !== undefined) {
+    parse(t.url, options.unsubscribeUrl, `${mail.id}.unsubscribeUrl`);
+  }
   const tz = options.tz ?? tryUseContext()?.tz ?? DEFAULT_TIME_ZONE;
   const rendered = renderMail(mail, input, {
     locale: options.locale,
@@ -150,6 +158,13 @@ export function renderMessage<I>(
   // Checked before the queue too, so the refusal lands on the `send()` call site that made it
   // rather than on a worker three retries later.
   assertHeaderSafe(message);
+  // The recipient rule, after the header gate so a line break keeps its own code: what the queue
+  // schema refuses is refused HERE, on every driver, rather than answered `queued: true` and then
+  // refused by the worker's parse — one rule on both paths (`s1-t4 #3`).
+  const replyTo = message.replyTo === undefined ? [] : [message.replyTo];
+  for (const address of [...envelopeRecipients(message), ...replyTo]) {
+    assertRecipientAddress('recipient', address);
+  }
   return message;
 }
 
@@ -167,21 +182,17 @@ export async function send<I>(
   // and the job never re-runs the hook. Not in `renderMessage`, which previews call.
   const message = await applyMailTransform(renderMessage(mail, data, options));
   const key = mailIdempotencyKey(message);
-  const queue = jobDriver();
 
-  if (options.sync === true || queue === undefined) {
+  if (options.sync === true || jobDriver() === undefined) {
     // The key is reported even inline, so a caller can dedupe its own retries either way.
     return { ...(await mailDriver().send(message)), idempotencyKey: key };
   }
 
-  const enqueued = await queue.enqueue({
-    name: sendMailJob.name,
-    queue: sendMailJob.queue,
-    input: message,
-    idempotencyKey: key,
-    maxAttempts: sendMailJob.retry.attempts,
-    onConflict: 'dedupe',
-  });
+  // Through the facade, never `queue.enqueue`: inside a transaction the row is STAGED on the
+  // caller's connection and published after COMMIT, so a handler that rolls back after sending
+  // mails nobody (`s1-con #3`). Outside one, the facade publishes straight to the same driver.
+  // The key is the handle's own `mailIdempotencyKey`, and the driver dedupes on it by default.
+  const enqueued = await jobsFacade().enqueue(sendMailJob, message);
 
   return {
     id: enqueued.id,

package/src/mime.ts

@@ -67,7 +67,7 @@ export function buildMimeMessage(message: MailMessage, options: MimeOptions): st
       // none for the addr-spec, and this package negotiates no SMTPUTF8 — so a UTF-8 mailbox would
       // go out as raw 8-bit octets in a header AND in the envelope beside it.
       if (mode === 'address' && hasNonAsciiAddrSpec(part))
-        throw headerInvalid(name, message.mailId);
+        throw headerInvalid(name, message.mailId, 'non-ascii');
     }
     headerLines.push(foldHeaderLine(name, parts.map((part) => encodeAs(mode, part)).join(', ')));
   };
@@ -79,9 +79,12 @@ export function buildMimeMessage(message: MailMessage, options: MimeOptions): st
   header('Date', rfc5322Date(options.date));
   header('Message-ID', options.messageId);
   header('MIME-Version', '1.0');
-  // RFC 8058 one-click unsubscribe and friends: computed once in driver.ts, emitted verbatim
-  // here so there is exactly one place that decides which of these headers a message gets.
-  for (const [name, value] of Object.entries(messageHeaders(message))) header(name, value);
+  // RFC 8058 one-click unsubscribe and friends: computed once in driver.ts so there is exactly one
+  // place that decides which of these headers a message gets. `Reply-To` is an ADDRESS and takes
+  // the address path — it went out verbatim, a non-ASCII display name as raw 8-bit octets.
+  for (const [name, value] of Object.entries(messageHeaders(message))) {
+    header(name, value, ADDRESS_HEADERS.has(name) ? 'address' : 'verbatim');
+  }
   header('Content-Type', `multipart/alternative; boundary="${options.boundary}"`);
 
   return `${headerLines.join(CRLF)}${CRLF}${CRLF}${buildBody(message, options.boundary)}`;
@@ -107,6 +110,9 @@ function bodyPart(contentType: string, text: string): string {
   );
 }
 
+/** The computed headers (`messageHeaders`) whose value is an address, not a 7-bit token. */
+const ADDRESS_HEADERS: ReadonlySet<string> = new Set(['Reply-To']);
+
 /**
  * How a header VALUE reaches the wire. `verbatim` is a value that is 7-bit by construction (a
  * date, a boundary, a message id); `value` is RFC 2047 over the whole string; `address` encodes
@@ -126,7 +132,7 @@ function encodeAs(mode: HeaderMode, value: string): string {
  * an 8-bit octet on a wire this package never negotiates SMTPUTF8 for, so it is the display name
  * that gets encoded — the addr-spec is copied through untouched, because a mailbox is the
  * server's to parse and an encoded word is not one. An address with no phrase, or an ASCII
- * phrase, comes back byte-identical.
+ * phrase with no special in it, comes back byte-identical; an ASCII phrase holding one is quoted.
  *
  * The MAILBOX is a different question and `hasNonAsciiAddrSpec` is where it is asked: RFC 2047
  * encoded words are legal in a phrase and nowhere else, so there is no encoding this function
@@ -136,8 +142,23 @@ export function encodeAddressPhrase(address: string): string {
   const match = ADDRESS_SPEC.exec(address);
   if (match === null) return address;
   const phrase = address.slice(0, match.index).trim();
-  if (phrase === '' || isPureAscii(phrase)) return address;
-  return `${encodeHeaderValue(phrase)} <${match[1] ?? ''}>`;
+  if (phrase === '') return address;
+  if (!isPureAscii(phrase)) return `${encodeHeaderValue(phrase)} <${match[1] ?? ''}>`;
+  if (!needsQuoting(phrase)) return address;
+  return `"${phrase.replace(/["\\]/g, (char) => `\\${char}`)}" <${match[1] ?? ''}>`;
+}
+
+/**
+ * RFC 5322 `specials` that end an atom, `.` aside (`obs-phrase` admits it, and `Jane Q. Doe` is
+ * every client's ordinary output). Unquoted, `Doe, Jane <jane@x.test>` is TWO list entries to the
+ * receiver — `Doe` and `Jane <jane@x.test>` — so the phrase is quoted rather than sent as written.
+ */
+const PHRASE_SPECIALS = /[(),:;<>@[\]\\"]/;
+
+/** A phrase that is already one whole quoted-string is the caller's own quoting, left alone. */
+function needsQuoting(phrase: string): boolean {
+  if (/^"(?:[^"\\]|\\.)*"$/.test(phrase)) return false;
+  return PHRASE_SPECIALS.test(phrase);
 }
 
 /**

package/src/render.ts

@@ -3,6 +3,7 @@
 // out of the HTML, so it never rots. Styling is inlined from the layout's tokens because most
 // clients drop <style>; the dark-mode block is the one exception, for clients that honour it.
 
+import { escapeHtml } from '@ultimat3/core';
 import { directionOf, type TranslateVars, type Translator, translatorFor } from '@ultimat3/i18n';
 import type { CalloutTone, MailBlock, MailTemplate } from './blocks';
 // The renderer depends on the strings it renders. This is the only module that resolves a `mail.*`
@@ -13,7 +14,7 @@ import type { CalloutTone, MailBlock, MailTemplate } from './blocks';
 // `registerMailCatalog()` themselves — the exact shape of issue #249.
 import './catalog';
 import { layoutUnknown, textMissing } from './errors';
-import { escapeHtml, safeUrl, styleAttr } from './html';
+import { safeUrl, styleAttr } from './html';
 import { layoutFor, registeredLayouts, token } from './layout';
 
 /** What the renderer needs from a mail. `MailDefinition` adds the input schema on top. */