5. Collapse Workflow Coordination into Mailbox Pipeline Domain Module

Date: 2026-08-24

Status

Accepted

Context

MailSweep provides operations for scanning headers (MailboxGateway.scan), evaluating clutter heuristics (ClassificationEngine.create_plan), auditing safety tier compliance (SafetyAuditor.audit), streaming offline backups (MailboxGateway.backup / BackupArchive), and executing mailbox cleanup (MailboxGateway.execute_cleanup).

Previously, coordinating these distinct operations was delegated entirely to callers and the CLI (src/mailsweep/cli.py):

1. Callers had to manually coordinate intermediate serialization files (scan_summary.json, targets_to_delete.json) on disk to bridge data across steps.
2. Programmatic consumers and headless automation (cron jobs, library scripts) had to replicate 50+ lines of connection management, UIDVALIDITY verification, and error handling.
3. Test suites had to orchestrate multiple distinct domain models and mock disk files to verify full-lifecycle behavior.
4. Business logic (percentage metrics, safety pre-flight assertions, backup verification before deletion) leaked into CLI entrypoints.

Decision

We deepened the end-to-end lifecycle orchestration into a domain module:

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

   • Encapsulates MailboxGateway, ClassificationEngine, SafetyAuditor, and BackupArchive behind a unified deep interface.
   • Accepts injected instances for in-memory testing (MailboxPipeline(gateway, engine=None, auditor=None)).
   • Provides a context-managed production factory: with MailboxPipeline.connect(config, transport=None) as pipeline:.
   • Offers atomic execution via pipeline.sweep(...) -> SweepSummaryReport as well as cohesive step operations (scan(), plan(), audit(), backup(), clean()).
   • Supports optional disk persistence paths (save_summary=..., save_plan=...) while keeping intermediate data flow 100% in-memory by default.
   • Enforces pre-flight safety gating (verifying UIDVALIDITY snapshot match and asserting clean audit or verified backup before allowing destructive cleanup).

2. SweepSummaryReport:

   • Pure, immutable domain model encapsulating ScanResult, CleanupPlan, BackupArchive | None, CleanupReport, SafetyAuditReport | None, and elapsed duration.
   • Formats human-readable CLI outputs via .render_text() and JSON metrics via .to_dict().

3. CLI Integration & Console Command:

   • Registered mailsweep sweep subcommand in src/mailsweep/cli.py for one-shot automated execution.
   • Streamlined individual subcommands (mailsweep scan, mailsweep plan, mailsweep backup, mailsweep clean) to delegate through MailboxPipeline.

4. Domain Vocabulary:

   • Formally registered Mailbox Pipeline and Sweep Summary Report in CONTEXT.md.

Consequences

• Full mailbox lifecycle can be executed in-memory or headless via a single method call.
• Zero disk round-trips required between pipeline stages.
• Pre-flight safety invariants are strictly enforced inside the domain module, preventing accidental unsafe deletions.
• Full testability with FakeImapTransport in under 0.05 seconds with zero mock disk I/O.