feat: start mailbox evidence scanner

src/email_connect/adapter_contract.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+ADAPTER_ID = "email-connect"
+ADAPTER_CONTRACT_VERSION = "1.1"
+
+EMITTED_EVENT_TYPES = [
+    "notification.endpoint.rejected_permanent",
+    "notification.endpoint.rejected_temporary",
+    "notification.endpoint.deferred",
+    "notification.channel.complaint_received",
+    "notification.channel.unsubscribe_received",
+    "interaction.reply_received",
+    "interaction.out_of_office_received",
+    "notification.endpoint.unknown",
+]
+
+
+def adapter_descriptor() -> dict:
+    """Return the initial coordination-engine adapter descriptor."""
+
+    return {
+        "adapter_id": ADAPTER_ID,
+        "adapter_name": "email-connect",
+        "adapter_version": "0.1.0",
+        "adapter_contract_version": ADAPTER_CONTRACT_VERSION,
+        "adapter_types": ["notification", "communication", "interaction"],
+        "deployment_mode": "external",
+        "capability_profile": {
+            "can_notify": True,
+            "can_publish": False,
+            "can_deliver_payload": False,
+            "can_collect_payload": False,
+            "can_grant_access": False,
+            "can_revoke_access": False,
+            "can_observe_interaction": True,
+            "can_observe_identity": False,
+            "can_observe_authority": False,
+            "can_emit_delivery_receipts": False,
+            "can_emit_display_or_read_receipts": False,
+            "can_emit_return_or_failure_events": True,
+            "can_emit_late_events": True,
+            "can_cancel_after_dispatch": False,
+            "supports_webhooks": False,
+            "supports_polling": True,
+            "supports_idempotency": "adapter_managed",
+            "supports_endpoint_quality": True,
+            "supports_native_status_mapping": True,
+            "supports_golden_tests": True,
+            "limitations": [
+                "Mailbox evidence cannot prove inbox placement.",
+                "Reply, open, and click signals do not prove coordination result satisfaction.",
+            ],
+        },
+        "supported_actions": [],
+        "emitted_event_types": EMITTED_EVENT_TYPES,
+        "supported_channels": ["email"],
+        "supported_endpoint_types": ["email_address"],
+        "evidence_profile": {
+            "native_status_mapping_ref": "src/email_connect/evidence.py",
+            "golden_tests_ref": "tests/fixtures",
+        },
+        "evidence_ceiling": {
+            "max_positive_event": "interaction.reply_received",
+            "max_positive_strength": "medium",
+            "can_prove_human_awareness": False,
+            "can_prove_payload_access": False,
+            "can_prove_payload_delivery": False,
+            "can_prove_identity": False,
+            "can_prove_authority": False,
+            "can_prove_non_repudiation": False,
+            "limitations": [
+                "Email cannot reliably prove intended-recipient awareness.",
+                "Mailbox scanning observes return-channel evidence only.",
+            ],
+        },
+        "assurance_capability": {
+            "awareness_assurance": "weak",
+            "delivery_assurance": "none",
+            "identity_assurance": "none",
+            "authority_assurance": "none",
+            "non_repudiation_assurance": "none",
+        },
+        "identity_profile": {
+            "can_identify_actor": False,
+            "identity_limitations": ["Inbound mailbox evidence is not authenticated actor evidence."],
+        },
+        "late_event_policy": {
+            "accepts_late_events": True,
+            "late_event_notes": ["Bounces and replies may arrive after earlier acceptance evidence."],
+        },
+        "limitations": [
+            "No outbound sending in the first mailbox-scanner MVP.",
+            "No provider webhook integration in the first mailbox-scanner MVP.",
+            "No legal delivery assessment.",
+        ],
+    }