6. Decouple Gateway Orchestration into Mailbox Pipeline

Date: 2026-08-24

Status

Accepted

Context

MailboxGateway manages IMAP connection lifecycles, protocol negotiation (MOVE, UIDPLUS), folder encoding, and atomic message operations.

Previously, MailboxGateway also acted as a domain-level orchestrator by exposing backup(), execute_cleanup(), and restore_archive(). This caused several architectural issues:

1. MailboxGateway contained circular import workarounds (TYPE_CHECKING blocks and inside-function lazy imports of BackupArchive and CleanupPlan).
2. Domain operations were duplicated across MailboxGateway and MailboxPipeline, creating redundant pass-through delegation layers.
3. MailboxGateway expanded to over 1,000 lines with mixed responsibilities (low-level IMAP network protocol handling vs high-level file archive packaging and plan resolution).

Decision

We cleanly decoupled all high-level domain orchestration from MailboxGateway and concentrated it in MailboxPipeline:

1. MailboxGateway (src/mailsweep/gateway.py):

   • Stripped of backup(), execute_cleanup(), restore_archive(), and all lazy TYPE_CHECKING circular import workarounds.
   • Constrained to core IMAP protocol operations: folder selection, header scanning (fetch_headers), raw message streaming (fetch_raw_messages), and atomic mutations (trash_messages, move_messages, mark_read, append_message, find_trash_folder).

2. MailboxPipeline (src/mailsweep/pipeline.py):

   • pipeline.backup(...): Directly coordinates BackupArchive.create(...) by providing a message fetcher stream adapter connected to gateway.fetch_raw_messages.
   • pipeline.clean(...): Evaluates CleanupPlan.by_folder(), validates UIDVALIDITY snapshot invariants, and executes batch mutations via gateway.trash_messages(), gateway.move_messages(), and gateway.mark_read().
   • pipeline.restore(...): Manages the complete restore lifecycle from BackupArchive, enforcing automatic SHA-256 integrity verification before appending raw messages to the server.

3. CLI & Tests (src/mailsweep/cli.py, test_mailsweep.py):

   • Standardized all CLI restore execution (cmd_restore) through MailboxPipeline.restore(...).
   • Updated integration test fixtures to verify lifecycle workflows through MailboxPipeline.

Consequences

• MailboxGateway shrinks and focuses entirely on the IMAP protocol, eliminating circular import dependencies.
• MailboxPipeline is the single canonical coordinator for all end-to-end mailbox operations (scan, plan, audit, backup, clean, restore, sweep).
• Archive creation and restore operations are 100% testable in-memory with fake transport adapters.
• All 75 tests execute in ~0.35s with zero disk or network I/O.