Initial Commit

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

@@ -0,0 +1,38 @@
+# 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.