[spec] Deepen MailSweep Domain Architecture and Eliminate Shallow Modules #62

New issue

Open

opened 2026-08-31 00:29:08 +03:00 by jalmari · 0 comments

jalmari commented

2026-08-31 00:29:08 +03:00

Owner

Problem Statement

The MailSweep codebase contains shallow modules and domain leakage across seams. Specifically:

The Scan Cache module is a shallow pass-through structure that exposes three static methods but delegates all logic to Scan Result.
The Cleanup Plan domain model strips vital metadata from EmailHeader items into a lossy TargetEmail structure. This loss forces the Safety Auditor to synthesize dummy EmailHeader items with blank fields during safety audits.
The Unsubscribe Hub module duplicates archive exploration, ZIP decompression, and manual header synthesis rather than delegating to Mailbox Pipeline and Backup Archive.
The Mailbox Gateway mixes raw IMAP transport operations with domain caching policies, delta UID calculation, and Gmail cross-folder label enrichment.

These architectural friction points increase cognitive load, create testing overhead, and leak domain logic across module seams.

Solution

Deepen the domain modules behind clear, cohesive seams:

Eliminate the shallow Scan Cache module by moving cache path resolution and atomic persistence directly into Scan Result and Mailbox Pipeline.
Deepen TargetEmail and Cleanup Plan to preserve authentic EmailHeader instances, eliminating synthetic dummy header creation in Safety Auditor.
Narrow the Unsubscribe Hub seam so it consumes pure in-memory EmailHeader collections, delegating file loading and archive extraction to Mailbox Pipeline.
Decouple delta caching and Gmail label deduplication from Mailbox Gateway, keeping the gateway focused purely on IMAP protocol communication.

User Stories

As a developer, I want Scan Result to handle its own cache file path derivation and persistence, so that callers do not need a shallow pass-through wrapper module.
As a developer, I want Mailbox Pipeline to coordinate scan caching directly with Scan Result, so that cache loading logic is contained in one place.
As a developer, I want TargetEmail to retain full EmailHeader domain metadata, so that downstream modules do not lose header fields.
As a safety engineer, I want Safety Auditor to evaluate authentic EmailHeader instances from Cleanup Plan, so that safety rules run on real data without synthetic dummy objects.
As a developer, I want Unsubscribe Hub to accept in-memory EmailHeader slices, so that brand aggregation does not depend on direct filesystem I/O.
As a developer, I want Mailbox Pipeline to load headers from scan summaries and backup archives before calling Unsubscribe Hub, so that orchestration stays in the pipeline coordinator.
As an IMAP integrator, I want Mailbox Gateway to focus on protocol commands and message transfer, so that transport fakes remain simple.
As a developer, I want Mailbox Pipeline to manage delta header merging and Gmail deduplication, so that domain policies stay decoupled from protocol transport.
As a tester, I want to test brand aggregation without mocking ZIP archives on disk, so that unit tests execute quickly in memory.
As a maintainer, I want all tests to pass clippy lints and formatting checks, so that the codebase remains robust and standard-compliant.

Implementation Decisions

Eliminate ScanCache struct in favor of ScanResult cache path methods and direct load/save methods on ScanResult. Remove src/cache.rs.
Enhance TargetEmail to retain EmailHeader domain metadata.
Refactor SafetyAuditor to remove synthetic header creation and evaluate headers directly from CleanupPlan.
Refactor UnsubscribeHub methods to accept EmailHeader slices instead of reading paths internally.
Update MailboxPipeline to coordinate scan caching, header loading, and sweep orchestration cleanly.
Keep existing public CLI flags and command behaviors fully backwards-compatible.

Testing Decisions

A good test exercises domain behavior across module interfaces with realistic in-memory fixtures, avoiding mocks of internal implementation details.

Tests will target MailboxPipeline, SafetyAuditor, CleanupPlan, UnsubscribeHub, and ScanResult.
Prior art includes existing test suites in tests/test_pipeline_and_audit.rs, tests/test_codecs_and_models.rs, and tests/test_gateway_and_cache.rs.

Out of Scope

Changes to the external CLI interface or command-line arguments.
Modifications to 13-language heuristic classification rules or regex patterns.
Async runtime migrations (synchronous Rust architecture is preserved per ADR-0008).

Further Notes

This refactoring aligns with ADR-0001, ADR-0005, ADR-0006, and ADR-0007.

## Problem Statement The MailSweep codebase contains shallow modules and domain leakage across seams. Specifically: 1. The Scan Cache module is a shallow pass-through structure that exposes three static methods but delegates all logic to Scan Result. 2. The Cleanup Plan domain model strips vital metadata from EmailHeader items into a lossy TargetEmail structure. This loss forces the Safety Auditor to synthesize dummy EmailHeader items with blank fields during safety audits. 3. The Unsubscribe Hub module duplicates archive exploration, ZIP decompression, and manual header synthesis rather than delegating to Mailbox Pipeline and Backup Archive. 4. The Mailbox Gateway mixes raw IMAP transport operations with domain caching policies, delta UID calculation, and Gmail cross-folder label enrichment. These architectural friction points increase cognitive load, create testing overhead, and leak domain logic across module seams. ## Solution Deepen the domain modules behind clear, cohesive seams: 1. Eliminate the shallow Scan Cache module by moving cache path resolution and atomic persistence directly into Scan Result and Mailbox Pipeline. 2. Deepen TargetEmail and Cleanup Plan to preserve authentic EmailHeader instances, eliminating synthetic dummy header creation in Safety Auditor. 3. Narrow the Unsubscribe Hub seam so it consumes pure in-memory EmailHeader collections, delegating file loading and archive extraction to Mailbox Pipeline. 4. Decouple delta caching and Gmail label deduplication from Mailbox Gateway, keeping the gateway focused purely on IMAP protocol communication. ## User Stories 1. As a developer, I want Scan Result to handle its own cache file path derivation and persistence, so that callers do not need a shallow pass-through wrapper module. 2. As a developer, I want Mailbox Pipeline to coordinate scan caching directly with Scan Result, so that cache loading logic is contained in one place. 3. As a developer, I want TargetEmail to retain full EmailHeader domain metadata, so that downstream modules do not lose header fields. 4. As a safety engineer, I want Safety Auditor to evaluate authentic EmailHeader instances from Cleanup Plan, so that safety rules run on real data without synthetic dummy objects. 5. As a developer, I want Unsubscribe Hub to accept in-memory EmailHeader slices, so that brand aggregation does not depend on direct filesystem I/O. 6. As a developer, I want Mailbox Pipeline to load headers from scan summaries and backup archives before calling Unsubscribe Hub, so that orchestration stays in the pipeline coordinator. 7. As an IMAP integrator, I want Mailbox Gateway to focus on protocol commands and message transfer, so that transport fakes remain simple. 8. As a developer, I want Mailbox Pipeline to manage delta header merging and Gmail deduplication, so that domain policies stay decoupled from protocol transport. 9. As a tester, I want to test brand aggregation without mocking ZIP archives on disk, so that unit tests execute quickly in memory. 10. As a maintainer, I want all tests to pass clippy lints and formatting checks, so that the codebase remains robust and standard-compliant. ## Implementation Decisions 1. Eliminate ScanCache struct in favor of ScanResult cache path methods and direct load/save methods on ScanResult. Remove src/cache.rs. 2. Enhance TargetEmail to retain EmailHeader domain metadata. 3. Refactor SafetyAuditor to remove synthetic header creation and evaluate headers directly from CleanupPlan. 4. Refactor UnsubscribeHub methods to accept EmailHeader slices instead of reading paths internally. 5. Update MailboxPipeline to coordinate scan caching, header loading, and sweep orchestration cleanly. 6. Keep existing public CLI flags and command behaviors fully backwards-compatible. ## Testing Decisions A good test exercises domain behavior across module interfaces with realistic in-memory fixtures, avoiding mocks of internal implementation details. - Tests will target MailboxPipeline, SafetyAuditor, CleanupPlan, UnsubscribeHub, and ScanResult. - Prior art includes existing test suites in tests/test_pipeline_and_audit.rs, tests/test_codecs_and_models.rs, and tests/test_gateway_and_cache.rs. ## Out of Scope - Changes to the external CLI interface or command-line arguments. - Modifications to 13-language heuristic classification rules or regex patterns. - Async runtime migrations (synchronous Rust architecture is preserved per ADR-0008). ## Further Notes This refactoring aligns with ADR-0001, ADR-0005, ADR-0006, and ADR-0007.

jalmari added the

ready-for-agent

spec

labels

2026-08-31 00:29:08 +03:00

jalmari referenced this issue

2026-08-31 00:29:16 +03:00

[arch] Eliminate shallow ScanCache and consolidate cache lifecycle into ScanResult #63

jalmari referenced this issue

2026-08-31 00:29:16 +03:00

[arch] Preserve EmailHeader in TargetEmail and eliminate synthetic header reconstruction in SafetyAuditor #64

jalmari referenced this issue