tegwick
3497ca88bf
Adds harness.deliver_raw() to inject crafted .eml fixtures through the harness, so they pick up the real Received: headers an MTA adds, and harness.inject_maildir() as the byte-exact offline counterpart. tests/test_evidence_realism.py asserts all ten recognized evidence classes after passing through a real MTA, proves MTA delivery does not change which evidence is produced, and covers Maildir injection offline. Documents what no local server can honestly produce -- provider-generated DSNs, real 4xx deferral and retry, ISP feedback loops, provider suppression behavior, MX acceptance as distinct from provider acceptance -- and names SES simulator addresses as the staging path. That tier stays out of the test run because it needs real credentials. Adds docs/test-harness-tutorial.md covering the three test tiers and the start/send/scan/assert/reset walkthrough, with an explicit assertable/not-assertable list so the evidence ceiling is stated where tests get written. Adds a Maildir section to the mailbox report tutorial. Completes EMAIL-WP-0005. Suite: 85 passed with the harness up, 64 passed + 21 skipped with it down. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|---|---|---|
| .claude/rules | ||
| .forgejo/workflows | ||
| config | ||
| deploy/k8s/railiance | ||
| docs | ||
| registry | ||
| reports | ||
| spec | ||
| src/email_connect | ||
| tests | ||
| workplans | ||
| .custodian-brief.md | ||
| .gitignore | ||
| .repo-classification.yaml | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| Containerfile | ||
| DECISIONS.md | ||
| INTENT.md | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| SCOPE.md | ||
| WORK-RECORDS.md | ||
email-connect
Headless, provider-neutral email communication and evidence service.
The first implementation slice is the Mailbox Evidence Scanner MVP: scan a return mailbox or fixture directory, classify inbound email-channel evidence, store scan state locally, and generate timestamped CSV reports without overclaiming delivery, awareness, or coordination success.
Quickstart
PYTHONPATH=src python3 -m unittest discover -s tests
PYTHONPATH=src python3 -m email_connect.cli adapter-descriptor
PYTHONPATH=src python3 -m email_connect.cli scan-mailbox --config config/mailbox.example.yml --out reports/
PYTHONPATH=src python3 -m email_connect.cli scan-mailbox --config config/mailbox.example.yml --expected-recipients tests/fixtures/expected_recipients.txt --out reports/
The example config uses tests/fixtures/mailbox as a mailbox source. Runtime
state is written to .email-connect/state.sqlite; generated CSV reports are
written to reports/.
Expected recipients are optional. When provided as a text file or CSV, reports
include a known_recipient column, place known recipients first, and add
undef.no_signal diagnostics for expected recipients with no mailbox evidence.
See Mailbox Report Tutorial.
For a live mailbox, set mailbox.protocol: imap, configure host, port, folder,
and credential environment variable names, then export the credentials before
running scan-mailbox. IMAP scans select the configured folder read-only and
fetch message bodies with BODY.PEEK[]; mailbox write-back actions such as
marking messages seen are intentionally unsupported in this MVP.
Current Scope
- Coordination-engine spec review and references.
- Initial adapter descriptor, capability profile, evidence ceiling, and limitations.
- Fixture and read-only IMAP mailbox sources.
- Conservative mailbox message parser and evidence mapper.
- SQLite state store with scan cursor, message/evidence deduplication, and endpoint quality hints.
- CSV report generation, including
--report-only-new. - Optional expected-recipient text/CSV input,
known_recipientreport filtering, no-evidence diagnostics, and datetime range filtering. - Golden fixture tests for hard bounce, soft bounce, delayed delivery, final failure, complaint, unsubscribe, challenge-response, unknown return, parse-failure, out-of-office, and human reply signals.
Provider webhooks, outbound sending, suppression workflows, OAuth mailbox login, and a UI remain outside this first mailbox-scanner slice.