agent-inbox 0.2.2 → 0.2.4

package/docs/MAIL-INTEROP-PLAN.md

@@ -0,0 +1,660 @@
+# Mail Interop — Implementation Plan
+
+Status: **proposed** · Branch: `claude/smtp-durable-inbox-gtUjJ`
+
+Bidirectional email interop for Agent Inbox: agents can receive email from and
+send email to external addresses, through a **pluggable `MailTransport`
+interface** with a **lightweight self-hosted SMTP backend as the default** and a
+**managed-provider backend** (SES / Postmark / Mailgun) as a drop-in alternative.
+
+This document focuses on **hardening the interface** — the contract every
+backend must satisfy — because the interface is the thing we can't cheaply
+change later. The two concrete backends are described only insofar as they
+prove the contract holds for both a raw-SMTP world and a provider-API world.
+
+---
+
+## 0. Design goals for the interface
+
+1. **Backend-agnostic.** The router, gateway, and storage layer must never know
+   whether mail is moving over self-hosted SMTP or a provider API. Same pattern
+   as `MapConnection` / `MapAgentConnectionClass` letting mesh and WebSocket
+   coexist per-peer.
+2. **Durable by contract, not by convention.** Inbound is committed before the
+   protocol ACK; outbound is enqueued durably before the first send attempt.
+   The interface makes the durability handoff explicit so a backend cannot
+   "forget" to be safe.
+3. **Honest error taxonomy.** Backends classify every failure as `permanent` /
+   `transient` / `unknown`. The retry/queue layer is driven by that
+   classification, never by string-matching SMTP text.
+4. **Capability negotiation, not assumption.** Backends advertise what they can
+   do (DKIM signing, inbound auth verification, MX delivery, webhooks). The
+   gateway adapts instead of assuming.
+5. **Untrusted-input posture baked in.** Inbound mail is hostile by default:
+   size caps, allow-lists, and auth-result surfacing are interface-level, not
+   per-backend afterthoughts.
+
+---
+
+## 1. The address-collision problem (must fix first)
+
+Email addresses are syntactically identical to federation addresses:
+
+```ts
+parseAddress("bob@gmail.com")  // → { agent: "bob", system: "gmail.com" }
+isRemoteAddress(...)           // → true   ← would route into ConnectionManager
+```
+
+Today `MessageRouter.routeMessage` (src/router/message-router.ts:94-105) sends
+anything with a `system` to federation. An email recipient would be silently
+swallowed by `ConnectionManager.route()` and dropped as "no route".
+
+### Resolution: a classified destination, computed once
+
+Introduce an explicit recipient classification step that runs **before** the
+federation branch. A destination is one of:
+
+| Class        | Shape                          | Routed to            |
+|--------------|--------------------------------|----------------------|
+| `local`      | `bob` (known agent)            | storage inbox        |
+| `federation` | `bob@system-2` (known peer)    | `ConnectionManager`  |
+| `mail`       | `bob@example.com` (mail domain)| `MailGateway`        |
+
+**Decision (resolved): explicit-list classification, with federation-domain
+support.** Nothing is guessed from "looks like a domain". A destination is mail
+only if its domain is in an explicit list, federation only if its system is a
+configured peer, and an unknown `@x` is a hard error rather than a silent guess.
+Because some federation systems are legitimately addressed with domain-like ids
+(e.g. `team.corp.internal`), the classifier supports a federation peer
+*declaring its own domain(s)* so the same dotted form routes to federation when
+that's what the operator meant.
+
+Disambiguation rule (deterministic, in priority order):
+
+1. No `@` → `local`.
+2. `@<x>` where `<x>` matches a **configured federation peer `systemId`** *or*
+   one of that peer's declared `domains` → `federation`.
+3. `@<x>` where `<x>` (or its parent domain) is in the **configured mail
+   `localDomains` / `routableDomains`** → `mail`.
+4. Otherwise → **error** (`UnknownDestinationError`): the recipient is rejected
+   at routing time, surfaced to the sender, never silently dropped or guessed.
+
+So a single dotted form like `@corp.internal` is `federation` if a peer claims
+it, `mail` if mail config claims it, and an error if neither does. When a domain
+appears in *both* (operator misconfiguration), **federation wins** and we emit a
+`mail.config.conflict` warning at startup so it's visible.
+
+This lives in a new `classifyDestination(agentId, ctx)` helper in
+`src/router/destination.ts`, taking the set of known peer system ids + their
+declared domains + mail config, so the rule is data-driven and testable in
+isolation. **`parseAddress` is left untouched** — we add a layer above it rather
+than overloading its meaning.
+
+```ts
+export type Destination =
+  | { class: "local"; agentId: string }
+  | { class: "federation"; agentId: string; address: FederatedAddress }
+  | { class: "mail"; email: string; localAgentId?: string };
+
+export interface DestinationContext {
+  isLocalAgent: (id: string) => boolean;
+  federationPeers: Array<{ systemId: string; domains?: string[] }>;
+  mailDomains: string[]; // localDomains ∪ routableDomains
+}
+
+/** Throws UnknownDestinationError for rule-4 misses. */
+export function classifyDestination(agentId: string, ctx: DestinationContext): Destination;
+```
+
+> Hardening note: the federation check (rule 2) runs before the mail check
+> (rule 3) so a peer's declared domain always wins; the "no implicit guess"
+> rule-4 error and the both-lists conflict warning are covered by tests.
+
+---
+
+## 2. The `MailTransport` interface
+
+`src/mail/mail-transport.ts`
+
+```ts
+/** What a backend can do. The gateway adapts to these. */
+export interface MailCapabilities {
+  /** Backend can deliver to arbitrary public MX (self-hosted/SMTP) vs only
+   *  via its own API/relay (some providers). Informational for routing. */
+  outbound: "mx" | "relay" | "api";
+  /** Backend signs DKIM itself (provider) or we must sign before handing off. */
+  signsDkim: boolean;
+  /** Backend verifies SPF/DKIM/DMARC on inbound and reports results. */
+  verifiesInboundAuth: boolean;
+  /** Inbound arrives via a long-lived listener (SMTP) or push webhook. */
+  inbound: "listener" | "webhook" | "none";
+  /** Max message size the backend will accept, bytes. */
+  maxMessageBytes: number;
+}
+
+export type MailTransportState = "stopped" | "starting" | "ready" | "degraded" | "stopping";
+
+export interface MailTransport {
+  readonly capabilities: MailCapabilities;
+  readonly state: MailTransportState;
+
+  /** Idempotent. Resolves only when inbound is actually accepting (port bound /
+   *  webhook registered) so callers don't ACK before we can receive. */
+  start(): Promise<void>;
+
+  /** Graceful: stop accepting new inbound, finish in-flight, then release. */
+  stop(): Promise<void>;
+
+  /**
+   * Send one already-rendered outbound message.
+   * MUST be idempotent on `envelope.idempotencyKey`: a retry with the same key
+   * must not produce a duplicate external email.
+   * MUST NOT throw for delivery failures — return a classified result instead.
+   * MAY throw only for programmer error (e.g. called while stopped).
+   */
+  send(envelope: OutboundMail): Promise<MailSendResult>;
+
+  /**
+   * Register the single ingress handler. The transport calls it once per
+   * received message and MUST await it. Resolution of the handler = "durably
+   * accepted"; the transport only then ACKs the peer MTA / webhook (250 / 200).
+   * A thrown handler = NACK (4xx) so the sender retries — never silent drop.
+   */
+  onReceive(handler: InboundHandler): void;
+
+  /** Liveness for health endpoints and the degraded → ready transition. */
+  health(): Promise<MailHealth>;
+}
+
+export type InboundHandler = (mail: InboundMail) => Promise<void>;
+```
+
+### Why these shapes harden the contract
+
+- **`send` never throws on delivery failure.** Throw-vs-return is the most
+  common way pluggable transports leak backend quirks. Delivery outcomes are
+  *data* (`MailSendResult`), so the queue logic is identical for SMTP 4xx and a
+  provider's JSON `{ "error": "throttled" }`.
+- **`onReceive` handler resolution gates the ACK.** This is the durability
+  contract in the type system: a backend physically cannot ACK before our
+  storage commit returns, because the ACK is downstream of the awaited handler.
+- **`start()` resolves only when truly accepting.** Prevents the race where we
+  tell an agent "mail is on" before the socket is bound.
+- **Capabilities are read, not assumed.** The gateway uses `signsDkim` to decide
+  whether to sign, `maxMessageBytes` to reject early, `verifiesInboundAuth` to
+  decide whether to trust the auth verdict or compute its own.
+
+---
+
+## 3. Envelope types — the wire contract
+
+```ts
+export interface MailAddress {
+  /** RFC 5322 addr-spec, e.g. "bob@example.com". */
+  address: string;
+  /** Optional display name. */
+  name?: string;
+}
+
+export interface OutboundMail {
+  /** Stable key for idempotent send. Derived from inbox Message.id. */
+  idempotencyKey: string;
+  from: MailAddress;
+  to: MailAddress[];
+  cc?: MailAddress[];
+  bcc?: MailAddress[];
+  subject?: string;
+  /** Rendered bodies. At least one of text/html. */
+  text?: string;
+  html?: string;
+  /** RFC 5322 threading headers, already computed by the mapper. */
+  headers: {
+    messageId: string;          // our Message-ID for this email
+    inReplyTo?: string;         // parent's Message-ID
+    references?: string[];      // full chain
+  };
+  attachments?: MailAttachment[];
+  /** Opaque passthrough for backend-specific knobs (provider tags, etc.). */
+  backendHints?: Record<string, unknown>;
+}
+
+export interface InboundMail {
+  /** The peer-asserted envelope (MAIL FROM / RCPT TO), distinct from headers. */
+  envelopeFrom: string;
+  envelopeTo: string[];
+  from: MailAddress;
+  to: MailAddress[];
+  cc?: MailAddress[];
+  subject?: string;
+  text?: string;
+  html?: string;
+  headers: {
+    messageId?: string;
+    inReplyTo?: string;
+    references?: string[];
+    /** Everything else, lower-cased keys, for the mapper to mine. */
+    raw: Record<string, string | string[]>;
+  };
+  attachments?: MailAttachment[];
+  /** Auth verdict — present iff capabilities.verifiesInboundAuth. */
+  authResults?: InboundAuthResults;
+  /** Peer IP / hostname, for allow-listing and abuse control. */
+  remote?: { ip?: string; reverseDns?: string };
+  /**
+   * Bounce/DSN classification, parsed from `Content-Type: multipart/report;
+   * report-type=delivery-status` (RFC 3464). Present when this inbound mail is
+   * a bounce, so the gateway can correlate it to the failed outbound send and
+   * drive the §8 bounce path instead of treating it as a fresh message.
+   */
+  bounce?: InboundBounce;
+  sizeBytes: number;
+  receivedAt: string; // ISO
+}
+
+export interface InboundBounce {
+  /** "failed" (permanent), "delayed" (transient), "delivered" (positive DSN). */
+  action: "failed" | "delayed" | "delivered";
+  /** The address that bounced. */
+  recipient: string;
+  /** RFC 3463 status code, e.g. "5.1.1". */
+  status?: string;
+  /** Message-ID of the original outbound mail, when the DSN echoes it. */
+  originalMessageId?: string;
+  diagnostic?: string;
+}
+
+export interface InboundAuthResults {
+  spf: "pass" | "fail" | "softfail" | "neutral" | "none";
+  dkim: "pass" | "fail" | "none";
+  dmarc: "pass" | "fail" | "none";
+}
+
+export interface MailAttachment {
+  filename?: string;
+  contentType: string;
+  contentId?: string;       // for inline html
+  /** Stored out-of-band; the envelope carries a handle, not megabytes. */
+  contentRef: string;
+  sizeBytes: number;
+}
+```
+
+### `MailSendResult` — the error taxonomy that drives retries
+
+```ts
+export type MailSendDisposition = "delivered" | "transient" | "permanent";
+
+export interface MailSendResult {
+  disposition: MailSendDisposition;
+  /** Provider/SMTP id when delivered, for correlating DSNs/bounces. */
+  remoteMessageId?: string;
+  /** Numeric SMTP-style code when available (e.g. 250, 451, 550). */
+  code?: number;
+  /** Human-readable, for logs only — never parsed for control flow. */
+  detail?: string;
+  /** For transient: hint for next attempt (e.g. greylist retry-after). */
+  retryAfterMs?: number;
+}
+```
+
+- `delivered` → dequeue, mark recipient `delivered_at`.
+- `transient` → keep in queue, schedule retry (honoring `retryAfterMs`), respect
+  `maxTTL` / `retryMaxAttempts` from `DeliveryQueueConfig`.
+- `permanent` → dequeue, emit `mail.bounced`, optionally synthesize a bounce
+  message back into the sender's inbox.
+
+This is the single most important hardening decision: **all backends collapse
+their native failure modes into these three**, so `delivery-queue.ts` needs no
+backend-specific knowledge.
+
+---
+
+## 4. The two backends (proving the contract)
+
+### 4a. Self-hosted SMTP — the default
+
+`src/mail/smtp-transport.ts`
+
+- **Inbound:** `smtp-server` listener. On `DATA` end → parse (`mailparser`) →
+  build `InboundMail` → `await handler(mail)` → only then ACK 250. Handler throw
+  → respond 451 (transient) or 550 (permanent) based on the thrown error type.
+- **Outbound:** `nodemailer` configured for direct-to-MX (default) or smarthost
+  relay. Maps SMTP responses → `MailSendResult`: 2xx→`delivered`,
+  4xx→`transient`, 5xx→`permanent`.
+- **Capabilities:** `{ outbound: "mx", signsDkim: true (we sign via nodemailer
+  DKIM), verifiesInboundAuth: true (mailauth), inbound: "listener",
+  maxMessageBytes: configurable }`.
+- Lightweight, zero external service, ideal for dev / internal / allow-listed
+  peers.
+
+### 4b. Managed provider — the swap-in (**Postmark first**)
+
+`src/mail/provider-transport.ts`
+
+Phase 4 targets **Postmark** because its inbound and bounce webhooks map ~1:1
+onto the types we hardened in §3 — least impedance to a passing contract suite,
+and it genuinely exercises the distinct webhook/DSN path (unlike SES, whose
+raw-MIME-in-S3 inbound just re-runs the SMTP parser). Postmark's transactional
+deliverability also matches agent traffic shape.
+
+- **Inbound:** Postmark inbound webhook POSTs fully parsed JSON (stripped reply
+  text, attachments, SPF/DKIM results) → `InboundMail` → `await handler` →
+  respond 200 only after commit; 5xx to make Postmark retry. Postmark's
+  **separate bounce webhook** delivers typed bounce records → `InboundBounce`
+  (§3) directly.
+- **Outbound:** Postmark REST API; map API responses → `MailSendResult`
+  (200 → `delivered`, 4xx throttle/transient → `transient`, hard reject →
+  `permanent`).
+- **Capabilities:** `{ outbound: "api", signsDkim: true (provider), inbound:
+  "webhook", verifiesInboundAuth: true, ... }`.
+
+Both satisfy the *same* interface; the gateway and router are unchanged when
+swapping. You can even run SMTP inbound + provider outbound by composing two
+transports behind a `CompositeMailTransport` (future, not in scope).
+
+> **SES remains the documented cost-at-scale alternative.** The interface makes
+> it a config swap, not a rewrite, so "Postmark to prove the contract, SES if
+> per-email cost dominates at high volume" costs nothing later. SES inbound,
+> when added, reuses the SMTP `mailparser` path on raw MIME pulled from S3/SNS.
+
+---
+
+## 4c. Attachment storage — `AttachmentStore` (SQLite default)
+
+`src/mail/attachment-store.ts`
+
+`MailAttachment.contentRef` is opaque (§3), so attachment bytes live behind a
+small swappable store that mirrors the existing `Storage`-with-two-impls
+pattern:
+
+```ts
+export interface AttachmentStore {
+  /** Returns a content-addressed ref (sha256-based). Dedups identical bytes. */
+  put(bytes: Buffer, meta: { contentType: string; filename?: string }): Promise<string>;
+  get(ref: string): Promise<Buffer>;
+  delete(ref: string): Promise<void>;
+}
+```
+
+- **Default: `SqliteAttachmentStore`** — bytes in an `attachments` BLOB table.
+  Commits **atomically** with the message (one transaction), single-file backup,
+  no orphan GC, and works with the in-memory DB tests already use. Zero-config.
+- **Opt-in: `FsAttachmentStore`** — content-addressed files
+  (`<dataDir>/attachments/<sha256>`) for large/high-volume deployments. Keeps the
+  DB small, streams big files, avoids blocking the synchronous `better-sqlite3`
+  loop. Writes file **before** committing the row, so a crash leaves a GC-able
+  orphan file, never a row pointing at missing bytes.
+- **Caps:** configurable per-attachment + total size, tied to
+  `capabilities.maxMessageBytes`; over-cap → reject inbound (NACK) or store
+  metadata-only (drop bytes, keep the `MailAttachment` record) per policy.
+- Content-addressing by sha256 gives free dedup and dovetails with the inbound
+  dedup story (§7b).
+
+---
+
+## 5. The mapper — `email-mapper.ts`
+
+Parallels `src/mesh/type-mapper.ts` exactly. Two pure functions:
+
+- `inboundMailToMessage(mail, ctx): Message`
+  - `from.address` → `sender_id` (the external email, kept verbatim).
+  - `to`/`cc` → recipients with `kind`; resolve each to an owning agent via the
+    address book (§6); unknown local recipients rejected before commit.
+  - `subject` → `subject`.
+  - `headers.messageId` → carried in `metadata.rfcMessageId`; **also the dedup
+    key** (§7).
+  - `headers.inReplyTo` / `references` → `in_reply_to` + `thread_tag`
+    (hash of root `References` id) so email threads map onto inbox threads.
+  - `authResults`, `remote`, `envelopeFrom` → `metadata` (for audit/abuse).
+  - Body → `normalizeContent` (text preferred; html retained in metadata).
+- `messageToOutboundMail(msg, ctx): OutboundMail`
+  - Inverse. `Message.id` → `idempotencyKey` and basis for `headers.messageId`.
+  - `in_reply_to` → look up parent's stored `rfcMessageId` → `inReplyTo` +
+    `references` chain so external clients thread correctly.
+
+Reuses `INBOX_META_KEYS`-style stripping so round-tripping doesn't leak control
+fields into user-visible metadata.
+
+---
+
+## 6. Identity / address book — `address-book.ts`
+
+Maps between agent ids and email addresses, and declares which domains we own.
+
+```ts
+export interface MailIdentityConfig {
+  /** Domains we receive for; inbound RCPT TO outside these is rejected. */
+  localDomains: string[];
+  /** agent_id → primary email, and reverse. Plus-addressing aware. */
+  mappings: Array<{ agentId: string; address: string }>;
+  /** Default mailbox for unmatched-but-accepted inbound (e.g. a triage agent). */
+  catchAllAgentId?: string;
+}
+```
+
+- Inbound `agent+scope@domain` → agent `agent`, inbox `scope` (reuses existing
+  scope semantics).
+- Outbound: an agent's `from` is its mapped address, else a configured default
+  `noreply@localDomain`.
+- This is also where the §1 classifier sources its mail-domain list, so
+  classification and rendering agree on what "ours" means.
+
+---
+
+## 7. Durability & idempotency (the load-bearing prerequisite)
+
+### 7a. Finish the SQLite delivery queue
+
+`delivery-queue.ts` is memory-only today (the `persistence: "sqlite"` config
+value exists but is unimplemented). Mail makes durability mandatory:
+
+- Implement a `sqlite` persistence path: `enqueue` / `recordAttempt` /
+  `removeEntry` / `flush` / TTL-`tick` all backed by a `mail_queue` table.
+- Survive restart: on boot, reload pending entries and resume retry timers.
+- Default the queue to durable (or hard-warn on memory) whenever mail is enabled.
+
+### 7b. Inbound idempotency (at-least-once → exactly-once-effect)
+
+SMTP and webhooks both redeliver. Dedup on `headers.messageId`:
+
+- Add a storage method `hasSeenExternalId(id): boolean` + record on commit.
+- Mapper computes a fallback synthetic id (hash of from+date+subject+body) when
+  `Message-ID` is absent.
+- Duplicate → ACK success **without** re-injecting (we already have it).
+
+### 7c. Commit-before-ACK
+
+Enforced structurally by §2: the backend's ACK is downstream of the awaited
+`onReceive` handler, and the handler only resolves after `storage.putMessage`.
+No backend can ACK early without violating the type contract.
+
+---
+
+## 8. Router & gateway wiring
+
+`src/mail/mail-gateway.ts` owns ingress + egress and is the only mail-aware
+component the rest of the system touches.
+
+- **Ingress:** constructed with the `MailTransport`; calls
+  `transport.onReceive(mail => router.routeMessage(mapped))`. Applies allow-list
+  + size + auth-result policy *before* commit; rejects map to handler-throw →
+  NACK.
+- **Egress:** `MessageRouter.routeMessage` gains a third branch. After computing
+  recipients, partition by `classifyDestination` (§1):
+  - `local` → existing inbox path.
+  - `federation` → existing `ConnectionManager.route`.
+  - `mail` → `MailGateway.send(message)` which renders + enqueues durably, then
+    drives `transport.send` with the queue's retry loop.
+
+`MessageRouter` gets an optional `setMail(gateway)` mirroring
+`setFederation(...)`, so mail stays opt-in and the core compiles without it.
+
+### New events (mirroring federation events)
+
+- `mail.received` — inbound accepted and committed.
+- `mail.sent` — `delivered` disposition.
+- `mail.queued` — transient failure, retry scheduled.
+- `mail.bounced` — permanent failure (outbound `permanent` result *or* inbound
+  failed-DSN). Payload carries the original `Message.id` when correlatable.
+- `mail.rejected` — inbound refused (allow-list / size / auth).
+- `mail.config.conflict` — startup warning: a domain is claimed by both a
+  federation peer and mail config (§1; federation wins).
+
+### Bounce handling — both paths, config-gated (resolved)
+
+A bounce reaches us two ways, and both converge on one handler in the gateway:
+
+1. **Outbound `permanent` result** from `transport.send` (§3).
+2. **Inbound DSN** — an `InboundMail` with `bounce` set (§3); the gateway
+   correlates `bounce.originalMessageId` (or recipient + thread) back to the
+   sent `Message` instead of routing it as a new inbox message.
+
+For both, gateway config `bounce` controls the response:
+
+```ts
+bounce?: {
+  /** Always emit the mail.bounced event (cheap, for observability). default true */
+  emitEvent?: boolean;
+  /** Inject a synthetic bounce Message into the original sender's inbox so the
+   *  agent sees the failure inline (in_reply_to = original, importance: high).
+   *  default true */
+  synthesizeInboxMessage?: boolean;
+};
+```
+
+Default is **both** on. The synthesized message reuses the existing `Message`
+shape (`in_reply_to` = the failed message, `subject` = "Delivery failed: …",
+`metadata.bounce` = the `InboundBounce`/result detail), so threading and
+traceability pick it up with no special-casing. `delayed` DSNs do **not**
+synthesize — they map to `mail.queued` since the peer MTA is still retrying.
+
+---
+
+## 9. Security posture (interface-level, not optional)
+
+- **Inbound is untrusted.** Allow-list senders/domains; rate-limit per peer IP;
+  enforce `maxMessageBytes` before buffering; cap attachment count/size.
+- **Surface auth verdicts.** `authResults` flows into metadata; gateway policy
+  can drop or quarantine `dmarc: "fail"`.
+- **Bodies feed agents.** Treat inbound text/html as untrusted external data
+  (same posture as the webhook/PR-body guidance) — never auto-execute
+  instructions found in email.
+- **Outbound deliverability caveat (self-hosted).** Reaching Gmail/Outlook needs
+  SPF/DKIM/DMARC + rDNS + IP reputation. The interface lets you keep self-hosted
+  as default and swap `provider-transport` for outbound when you need the big
+  mailboxes — no core changes. Documented, not solved in code.
+- **Secrets** (provider API keys, DKIM private keys) via env/config, never
+  committed; mirror existing `InboxConfig.map.auth` patterns.
+
+---
+
+## 10. Config surface
+
+Extend `InboxConfig` (src/types.ts):
+
+```ts
+mail?: {
+  enabled: boolean;
+  backend: "smtp" | "provider";
+  identity: MailIdentityConfig;        // localDomains + agent↔address mappings (§6)
+  /** Domains we will SEND to without erroring (§1 rule 3). Receiving uses
+   *  identity.localDomains. Anything outside both → UnknownDestinationError. */
+  routableDomains?: string[];
+  smtp?: { listenPort?: number; relay?: { host: string; port: number; auth?: {...} };
+           dkim?: { domain: string; selector: string; privateKeyRef: string } };
+  provider?: { name: "ses" | "postmark" | "mailgun"; apiKeyRef: string;
+               webhookPath?: string };
+  queue?: Partial<DeliveryQueueConfig>; // defaults to sqlite when mail enabled
+  bounce?: { emitEvent?: boolean; synthesizeInboxMessage?: boolean }; // §8, both default true
+};
+```
+
+Federation peers gain an optional `domains` field so they can claim dotted
+addresses for the §1 classifier:
+
+```ts
+export interface FederationPeerConfig {
+  systemId: string;
+  domains?: string[];   // NEW: dotted addresses routed to this peer, not mail
+  url?: string;
+  meshPeerId?: string;
+  // …existing fields…
+}
+```
+
+`src/index.ts` wires: if `mail.enabled`, construct the backend per `backend`,
+build `MailGateway`, call `router.setMail(gateway)`, and register inbound.
+
+---
+
+## 11. Test plan (vitest, in-process — no real sockets/network)
+
+Follow the existing `MockMapServer` / `MockMeshContext` convention with a
+`MockMailTransport` (in-memory loopback implementing `MailTransport`).
+
+- `test/mail/destination.test.ts` — §1 classifier: local vs federation vs mail,
+  the `corp.internal` peer-wins case, dotted-domain detection, ordering.
+- `test/mail/email-mapper.test.ts` — round-trip; threading header ↔ thread_tag;
+  plus-addressing → scope; metadata stripping; missing Message-ID fallback id.
+- `test/mail/mail-transport-contract.test.ts` — a **shared contract suite** run
+  against `MockMailTransport` (and later each real backend): send idempotency on
+  duplicate key; `send` returns (never throws) on transient/permanent; ACK only
+  after handler resolves; handler-throw → NACK; `start` resolves when ready.
+- `test/mail/delivery-queue-sqlite.test.ts` — durable enqueue/flush/retry/TTL;
+  survives a simulated restart.
+- `test/mail/inbound-dedup.test.ts` — redelivered Message-ID committed once.
+- `test/mail/mail-gateway.test.ts` — ingress allow-list/size/auth rejection;
+  egress partitioning of mixed local+federation+mail recipients.
+- `test/mail/integration.test.ts` — agent ↔ external loopback both directions
+  via `MockMailTransport`.
+
+The shared contract suite is the real hardening payoff: any backend we add later
+must pass the *same* tests, so the interface stays honest.
+
+---
+
+## 12. Phasing — ✅ complete
+
+1. ✅ **Foundations:** §1 classifier + §7a SQLite queue + types (§2, §3) + config
+   (§10). No behavior change; everything compiles and tests green.
+2. ✅ **Mapper + address book** (§5, §6) + `MockMailTransport` + contract suite
+   (§11). Interface proven against a fake before any I/O.
+3. ✅ **Self-hosted SMTP backend** (§4a) + gateway wiring (§8, incl. both bounce
+   paths) + dedup (§7b/c). Default path working end-to-end, real-socket e2e.
+4. ✅ **Managed provider backend** (§4b, Postmark) — proves the swap; same
+   contract suite via a fake client. `AttachmentStore` SQLite default landed in
+   phase 2.
+5. ✅ **Hardening pass:** inbound rate limiting + abuse controls (attachment cap,
+   allow-list, DMARC), DSN parsing for the SMTP backend (`parseDsnFromParsed`),
+   docs in CLAUDE.md, plus a post-review pass (retry re-entrancy, bounce-replay
+   dedup, DSN false-positive fix, Postmark error classification, webhook
+   body-cap + basic-auth, address/attachment validation).
+6. ✅ **`FsAttachmentStore`:** opt-in filesystem attachment backend behind the
+   same `AttachmentStore` interface (content-addressed, atomic write-then-rename,
+   sharded, path-traversal-safe, with GC). Both backends pass a shared contract.
+
+Phases 1–2 are where the interface was locked; everything after was "fill in a
+backend that passes the contract suite."
+
+---
+
+## Resolved decisions
+
+1. **Classification (§1):** explicit-list only. Mail domains and federation
+   peer domains are both declared in config; an unknown `@x` is an
+   `UnknownDestinationError`, never a guess. Federation peers may claim
+   dotted domains, federation wins on conflict (with a `mail.config.conflict`
+   warning).
+2. **Bounce (§8):** both `emitEvent` and `synthesizeInboxMessage`, config-gated,
+   both defaulting on; inbound DSNs and outbound `permanent` results converge on
+   the same handler.
+3. **Provider (§4b):** **Postmark first** — inbound + typed bounce webhooks map
+   ~1:1 to our types, fastest contract proof. SES kept as documented
+   cost-at-scale alternative.
+4. **Attachments (§4c):** **`AttachmentStore` interface, SQLite BLOB default**
+   (atomic, zero-config, test-friendly); `FsAttachmentStore` opt-in for
+   large/high-volume. Content-addressed, size-capped.
+
+## Open questions for review
+
+*(none blocking — interface is locked; ready to build Phase 1.)*