Track SMTP submission robustness improvements

[bbottema]

SMTP callers need to know what the server accepted, when a retry could duplicate mail, and what happened when a connection failed. This tracks the independently reviewable improvements in 03_SMTP_ROBUSTNESS_IMPROVEMENT_PLAN.

The project builds on the 10.0.0 submission receipts (#710), terminal observer (#712), and exact EML support (#713). It does not add automatic retries, a durable spool, or mailbox-delivery guarantees.

Phase 1 (#723) and Phase 2 (#725 and #726) are complete and accepted. Phase 2 covers bounded queues, send completion handles, total deadlines, protocol-aware cancellation and application-executor observer dispatch, including managed-Angus socket abort and the released pool controls. These are unreleased 10.0.0 changes. The independent execution-view migration (#734) is also complete and accepted: sends, simple batches and connection tests now use Mailer.sync() or Mailer.async(), with receipts returned by every single-email send. Phase 3's SMTP capability-probe story (#733) is now complete and accepted: Java and CLI probes, optional authentication, safe capability/TLS reports, dedicated connections, partial-detail provider support, a runnable demo and website guidance. Both development branches are pushed and #733 is closed; these changes remain unreleased until 10.0.0 ships. Phase 3 is now complete: #735 is accepted, pushed and closed, with matching website guidance. It rejects extra properties that disable mandatory STARTTLS without changing the opportunistic SMTP default. Phase 4 has the approved ENVID-only slice available locally for review under #736: per-send DSN identifiers through the existing Angus MAIL extension hook. It remains uncommitted and In Progress pending acceptance. ORCPT and recipient-specific NOTIFY remain deferred under this parent; they are not acceptance criteria for #736. Later steps remain proposals; they can ship in separate releases.

Current send architecture

This maps the accepted pooled asynchronous send path, including the completed #726 implementation. The layers explain responsibilities; they are not a lock-order diagram.

Steps

Step	Child issue	Planned release	Shipped release	User-visible result
1	#723	10.0.0	—	Per-recipient replies and conservative retry guidance
2	#725	10.0.0	—	Bounded async demand and visible overflow
3	#726	10.0.0	—	Deadlines and protocol-aware cancellation
4	#733	10.0.0	—	SMTP capability diagnostics through Java and CLI (complete; unreleased)
4a	#734	10.0.0	—	Explicit sync/async execution views and unified receipt-returning sends (complete; unreleased)
5	#735	10.0.0	—	Reject contradictory mandatory STARTTLS settings; keep opportunistic SMTP as the default (complete; unreleased)
6	#736	10.0.0	—	ENVID send correlation (implementation in review); original-recipient metadata deferred
7	Not created	Unscheduled	—	Per-message REQUIRETLS
8	Not created	Unscheduled	—	SMTPUTF8 and 8BITMIME requirements
9	Not created	Unscheduled	—	SIZE against finalized transmitted bytes
10	Not created	Unscheduled	—	Reproducible conformance and fault-injection tests

Each scheduled step gets its own linked sub-issue, exact release milestone, tests, documentation, and release entry. Keep this parent open until the steps are completed or explicitly moved to a successor plan. PIPELINING/CHUNKING remain parked under #699. Benchmarking is outside the current work.

Keep the overview current

The canonical image lives at docs/concurrency/assets/inside-a-mail-send.png. The concurrency catalogue uses that master, the website uses an identical copy, and this issue embeds the master through the development branch.

Every remaining step must review the pictured class names, responsibilities, transport paths, cancellation boundaries, and outcome reporting. Record either an update or why the overview remains accurate; do not add proposed behavior or expand the picture for changes that still fit its existing layers.

• Phase 2: reviewed unchanged on 11 September 2026; the pictured cleanup and outcome boundaries match the completed implementation.
• Execution-view migration (Make Mailer execution mode explicit with sync and async views #734): reviewed unchanged on 13 September 2026; the cached views add no resource ownership or synchronization boundary.
• SMTP capability probe (Explain SMTP connection capabilities and TLS negotiation #733): reviewed unchanged at completion on 15 September 2026. Java/CLI probing and its partial-provider boundary stay outside the illustrated send, pool-lease and observer path.
• Phase 3: reviewed unchanged at completion on 15 September 2026. The Reject extra properties that disable mandatory STARTTLS #735 construction-time guard runs before send-operation, proxy, lifecycle and pool setup; it adds no send owner, lock, state transition or probe-to-send dependency. The catalogue, website copy and this embed retain the approved overview.
• ENVID-only slice (Add DSN envelope identifiers for send correlation #736): reviewed unchanged on 15 September 2026. A fresh per-message provider wrapper and capability check fit the existing transport layer; pool ownership, cancellation and observer ordering are unchanged. Implementation awaits acceptance.
• Phase 4: review envelope requirements, capability enforcement, and finalized-content checks.
• Phase 5: compare the overview with the conformance scenarios.
• Before the 10.0.0 release: reconcile the implementation, catalogue, website, and this image.

When the artwork changes, update the master, website copy, and this existing embed together. Refresh the image URL's revision query to avoid a cached older image; do not add a separate competing diagram attachment.

[bbottema]

The supporting-library part of #726 shipped on 8 September 2026: Generic Object Pool 2.5.0, Clustered Object Pool 4.1.0, and SMTP Connection Pool 4.1.0.

The release narrative is stopping abandoned jobs while they wait for pooled resources, with opt-in controls, one acquisition budget, safe ownership handoff and observable cleanup. SMTP additionally offers an explicit capability for providers that can safely abort their own transport.

This is supporting infrastructure, not yet a Simple Java Mail send-cancellation feature: downstream integration remains under #726, and built-in Angus physical abort is still unsupported. These additions are separate from the earlier waiter-wake-up patch releases.