1. Deepen Classification Safety Auditor into a Domain Module

Date: 2026-08-23

Status

Accepted

Context

MailSweep performs safety audits across scan summaries, cleanup plans, and offline backup archives to ensure no critical personal, medical, legal, financial, or direct conversation emails are targeted for deletion.

Previously, src/mailsweep/audit.py existed only as a procedural function (run_deep_audit) that loaded filesystem JSON snapshots, executed heuristics with direct standard output print() calls, and returned None. This prevented:

1. Pure in-memory unit testing without disk I/O or stdout capture.
2. Programmatic consumption of audit findings by automated pipelines or downstream gateways.
3. Verification of CleanupPlan and BackupArchive objects directly across a single deep interface.

Decision

We deepened the safety auditing capability into a domain module:

1. SafetyAuditor (aliased as ClassificationSafetyAuditor):

   • Accepts domain entities directly (ScanResult, BackupArchive, CleanupPlan, Sequence[EmailHeader], Sequence[ArchivedMessage], or path strings).
   • Injects ClassificationEngine via constructor (engine: ClassificationEngine | None = None) for test isolation.
   • Provides specialized operations: audit_scan(), audit_backup(), audit_plan(), and unified audit().

2. SafetyAuditReport & AuditFinding:

   • Pure, immutable dataclass models encapsulating total analyzed counts, partition metrics (trash_count, keep_count), categorized findings (critical_findings, receipt_findings, shipping_findings, suspicious_trash), and sender distributions.
   • Decoupled render_text() formatter for CLI display and to_dict() for JSON serialization.
   • Derived boolean properties: is_clean and has_warnings.

3. Domain Vocabulary:

   • Formally registered Classification Safety Auditor and Safety Audit Report in CONTEXT.md.

Consequences

• Callers and tests can evaluate mailbox datasets in-memory with zero side-effects.
• run_deep_audit remains fully backwards-compatible as a thin CLI wrapper delegating to SafetyAuditor.
• Improved maintainability and locality for 13-language European heuristic safety checks.