suaveplan/openspec/archive/2026-05-24-email-processing/proposal.md

Email Processing — universal-tier migration

Why

@suaveplan/email-processing is the canonical MIME + email-content processor for every downstream consumer that ingests email (campaigns, emailer, delivery-tracking, suppression, dmarc). The package exists on main at /mnt/s/web/suaveplan/packages/universal/email-processing at v1.2.3 with 96.23% coverage; the enterprise plan at /mnt/s/web/suaveplan/enterprise/email-processing.md demands a genesis-quality rewrite with Zod boundary validation, OTel instrumentation, structured error codes, injectable resolvers, and 100% coverage. This change lands the package fresh under the canonical 3-level layout (packages/communication/emails/email-processing/).

What changes

• New universal-tier package @suaveplan/email-processing@0.1.0.
• Wraps postal-mime and libmime via a strict TypeScript surface; no @ts-expect-error or any leaks.
• Adds EMAIL_PROCESSING_CODES (eight codes) and a EmailProcessingError class with a public constructor.
• Adds OTel instruments: parse counter, parse-failure counter, attachment processed / rejected counters, attachment-extraction duration histogram, hook-invocation counter, DKIM/SPF/DMARC result counters, spam-classification counter, threads-grouped counter.
• Replaces the upstream @suaveplan/events/hooks substrate (which does not exist in genesis yet) with an in-package Hooks<TMap> pipeline so the public email:processing surface is preserved.
• 100% statement / branch / function / line coverage (Istanbul).
• No mocks: DKIM round-trip is exercised with a real RSA keypair generated via Web Crypto.

Impact

• Affected specs: email-processing (new capability).
• Affected code: new package only — no consumers migrated yet.
• Catalog: adds postal-mime and libmime to the parsing catalog.