[spec] Deepen Mailbox Pipeline and Seal Domain Seams

jalmari commented

2026-08-30 12:36:39 +03:00

Owner

Problem Statement

The command-line interface module (cli.py) contains more than 600 lines of code with procedural orchestration logic. Subcommands directly instantiate and wire intermediate domain models and tools (ClassificationEngine, SafetyAuditor, UnsubscribeHub, ScanResult). This causes architectural friction:

Callers bypass the central MailboxPipeline domain coordinator for offline operations (plan, audit, verify, unsubscribe).
Subcommands use uncoordinated instantiation workarounds (such as passing a null gateway to MailboxPipeline).
Module seams leak: SafetyAuditor inspects the private attribute _crit_re of ClassificationEngine.

Solution

Deepen the domain modules and consolidate orchestration seams:

Deepen ClassificationEngine by adding public safety query methods, removing private regex access across module seams.
Deepen MailboxPipeline to support both online and offline operations through unified domain methods.
Refactor cli.py to be a thin adapter that parses command arguments and delegates all orchestration to MailboxPipeline.

User Stories

As a CLI user, I want all subcommands to execute through the unified MailboxPipeline coordinator, so that operations remain consistent across CLI, API, and tests.
As a CLI user, I want offline operations (plan, audit, verify, unsubscribe) to run without IMAP connection requirements, so that local snapshots are analyzed safely.
As a developer, I want ClassificationEngine to expose explicit public safety query methods, so that SafetyAuditor does not access private engine internals.
As a developer, I want MailboxPipeline to provide an offline factory method, so that testing and script automation do not construct invalid gateway instances.
As a maintainer, I want cli.py to contain only argument parsing and output presentation logic, so that domain rules remain localized in domain modules.
As a test author, I want to verify full offline and online workflows through the MailboxPipeline interface, so that test setup stays concise and high-leverage.

Implementation Decisions

Seam Placement: MailboxPipeline is the single high-level domain coordinator seam. ClassificationEngine is the single heuristic classification and safety query seam.
Engine Encapsulation: Add public methods is_critical_subject(subject) and audit_safety(items) on ClassificationEngine.
Pipeline Deepening: Add MailboxPipeline.offline() factory and integrate audit, unsubscribe, and plan orchestration into MailboxPipeline.
CLI Adapter Slimming: Refactor cmd_plan, cmd_audit, cmd_verify, and cmd_unsubscribe in cli.py to delegate to MailboxPipeline.

Testing Decisions

Test all workflows at the MailboxPipeline seam using in-memory test stand-ins (FakeImapTransport, FakeUrlHealthChecker).
Test ClassificationEngine safety query methods directly with unit test assertions.
Verify full test suite passes with zero regressions.

Out of Scope

Modifying classification pattern heuristic dictionaries or language lists.
Redesigning HTML dashboards or changing CLI argument flags.
Adding new IMAP protocol extensions.

Further Notes

Follows ADR-0005 and ADR-0006 architecture principles. Complies with ASD-STE100 language rules.

## Problem Statement The command-line interface module (`cli.py`) contains more than 600 lines of code with procedural orchestration logic. Subcommands directly instantiate and wire intermediate domain models and tools (`ClassificationEngine`, `SafetyAuditor`, `UnsubscribeHub`, `ScanResult`). This causes architectural friction: 1. Callers bypass the central `MailboxPipeline` domain coordinator for offline operations (`plan`, `audit`, `verify`, `unsubscribe`). 2. Subcommands use uncoordinated instantiation workarounds (such as passing a null gateway to `MailboxPipeline`). 3. Module seams leak: `SafetyAuditor` inspects the private attribute `_crit_re` of `ClassificationEngine`. ## Solution Deepen the domain modules and consolidate orchestration seams: 1. Deepen `ClassificationEngine` by adding public safety query methods, removing private regex access across module seams. 2. Deepen `MailboxPipeline` to support both online and offline operations through unified domain methods. 3. Refactor `cli.py` to be a thin adapter that parses command arguments and delegates all orchestration to `MailboxPipeline`. ## User Stories 1. As a CLI user, I want all subcommands to execute through the unified `MailboxPipeline` coordinator, so that operations remain consistent across CLI, API, and tests. 2. As a CLI user, I want offline operations (`plan`, `audit`, `verify`, `unsubscribe`) to run without IMAP connection requirements, so that local snapshots are analyzed safely. 3. As a developer, I want `ClassificationEngine` to expose explicit public safety query methods, so that `SafetyAuditor` does not access private engine internals. 4. As a developer, I want `MailboxPipeline` to provide an offline factory method, so that testing and script automation do not construct invalid gateway instances. 5. As a maintainer, I want `cli.py` to contain only argument parsing and output presentation logic, so that domain rules remain localized in domain modules. 6. As a test author, I want to verify full offline and online workflows through the `MailboxPipeline` interface, so that test setup stays concise and high-leverage. ## Implementation Decisions - **Seam Placement**: `MailboxPipeline` is the single high-level domain coordinator seam. `ClassificationEngine` is the single heuristic classification and safety query seam. - **Engine Encapsulation**: Add public methods `is_critical_subject(subject)` and `audit_safety(items)` on `ClassificationEngine`. - **Pipeline Deepening**: Add `MailboxPipeline.offline()` factory and integrate `audit`, `unsubscribe`, and `plan` orchestration into `MailboxPipeline`. - **CLI Adapter Slimming**: Refactor `cmd_plan`, `cmd_audit`, `cmd_verify`, and `cmd_unsubscribe` in `cli.py` to delegate to `MailboxPipeline`. ## Testing Decisions - Test all workflows at the `MailboxPipeline` seam using in-memory test stand-ins (`FakeImapTransport`, `FakeUrlHealthChecker`). - Test `ClassificationEngine` safety query methods directly with unit test assertions. - Verify full test suite passes with zero regressions. ## Out of Scope - Modifying classification pattern heuristic dictionaries or language lists. - Redesigning HTML dashboards or changing CLI argument flags. - Adding new IMAP protocol extensions. ## Further Notes Follows ADR-0005 and ADR-0006 architecture principles. Complies with ASD-STE100 language rules.

jalmari added the

ready-for-agent

spec

labels

2026-08-30 12:36:39 +03:00

jalmari referenced this issue

2026-08-30 12:36:39 +03:00

[deepen] Encapsulate Safety Verification Seam on Classification Engine #34

jalmari referenced this issue

2026-08-30 12:36:39 +03:00

[deepen] Add Unified Offline Operations to Mailbox Pipeline #35

jalmari referenced this issue

2026-08-30 12:36:40 +03:00

[refactor] Collapse CLI Subcommands into Mailbox Pipeline Adapter #36

jalmari commented

2026-08-30 15:41:05 +03:00

Author

Owner

Implemented deep offline pipeline factory and public safety query methods on ClassificationEngine. Refactored CLI subcommands to delegate through MailboxPipeline. Full test suite passes with 129 tests.

jalmari closed this issue

2026-08-30 15:41:05 +03:00

jalmari referenced this issue from a commit

2026-08-30 15:52:16 +03:00

feat(pipeline): deepen MailboxPipeline and seal domain seams (#33)

jalmari referenced this issue from a pull request that will close it,

2026-08-30 16:03:23 +03:00

feat(pipeline): Deepen Mailbox Pipeline, Seal Domain Seams, and Unify CLI Adapter (Closes #33) #37

jalmari referenced this issue from a commit

2026-08-30 16:03:32 +03:00

Merge pull request 'feat(pipeline): Deepen Mailbox Pipeline, Seal Domain Seams, and Unify CLI Adapter (Closes #33)' (#37) from develop into main