docs(email): record send ledger evidence

2026-08-09 23:41:09 +02:00
parent 653f011be2
commit 429f427f49
7 changed files with 41 additions and 19 deletions
@@ -399,3 +399,13 @@
 - **Consequences:** users can distinguish live and saved content availability, malformed legacy metadata cannot break detail, and late responses cannot populate another selected row. The saved copy may be stale and is labeled as such when live access fails.
 - **User approval required:** No; this is local read-only behavior with synthetic/mocked tests and no provider invocation.
 - **Reversible:** Yes. Revert `a20775c`; no schema, dependency, provider scope or persisted data changes.
+
+## DEC-041 — Delivery idempotency is a content-free tenant ledger
+
+- **Date:** 2026-08-09
+- **Decision:** Persist one `EmailSendAttempt` per owner/client UUID with a SHA-256 payload hash and strict pending → sending → sent/failed/uncertain transitions. Terminal and uncertain attempts cannot restart; a new explicit review must use a new request UUID. Store no recipient, subject or body.
+- **Reason/evidence:** SMTP/provider calls cannot be made atomic with a database commit. A crash or transport interruption after acceptance is inherently uncertain, so retrying the same attempt can duplicate email. The ledger must exist before any provider scope/button is enabled and must preserve only the metadata needed for deduplication/audit.
+- **Alternatives considered:** rely on disabled buttons; store request IDs on correspondence; reuse AI operations; retry on every timeout; save full draft content in the audit row; add a message outbox that assumes provider idempotency. These do not prevent concurrent/direct-API duplicates, conflate domains, risk duplicate sends/private-data retention or promise atomicity the providers do not offer.
+- **Consequences:** API integration can reserve a unique attempt before external I/O and fail closed on pending/uncertain records. A provider success followed by database failure remains reconcilable rather than blindly retried. User export must include the non-sensitive metadata; job/account deletion cascades it. The migration is additive and EF-owned with explicit SQLite/MariaDB types.
+- **User approval required:** No; the approved MAIL-001 programme requires idempotent/uncertain send safety. This increment is inert and used no provider.
+- **Reversible:** Yes. Before reverting `653f011`, stop send admission, reconcile/drain attempts and downgrade `20260809195014_AddEmailSendAttempts`. No production migration has been applied.