Add cross-module operational and interaction contracts

src/govoplan_core/celery_app.py

@@ -24,7 +24,12 @@ from govoplan_core.core.idm import (
     IdmAssignmentLifecycle,
 )
 from govoplan_core.core.module_management import load_startup_enabled_modules, startup_candidate_module_ids
-from govoplan_core.core.mail import CAPABILITY_MAIL_DELIVERY_OUTBOX, MailDeliveryOutboxProvider
+from govoplan_core.core.mail import (
+    CAPABILITY_MAIL_BOUNCE_PROCESSING,
+    CAPABILITY_MAIL_DELIVERY_OUTBOX,
+    MailBounceProcessingProvider,
+    MailDeliveryOutboxProvider,
+)
 from govoplan_core.core.modules import ModuleContext
 from govoplan_core.core.notifications import CAPABILITY_NOTIFICATIONS_DISPATCH, NotificationDispatchProvider
 from govoplan_core.core.postbox import (
@@ -58,6 +63,7 @@ celery.conf.update(
         "govoplan.notifications.deliver_pending": {"queue": "notifications"},
         "govoplan.mail.dispatch_outbox": {"queue": "mail"},
         "govoplan.mail.purge_outbox": {"queue": "mail"},
+        "govoplan.mail.scan_bounces": {"queue": "mail"},
         "govoplan.calendar.dispatch_outbox": {"queue": "calendar"},
         "govoplan.dataflow.dispatch_runs": {"queue": "dataflow"},
         "govoplan.dataflow.purge_runs": {"queue": "dataflow"},
@@ -87,6 +93,11 @@ celery.conf.update(
             "schedule": 24 * 60 * 60.0,
             "args": (250,),
         },
+        "mail-bounces-every-five-minutes": {
+            "task": "govoplan.mail.scan_bounces",
+            "schedule": 5 * 60.0,
+            "args": (None, 250),
+        },
         "dataflow-triggers-every-minute": {
             "task": "govoplan.dataflow.dispatch_triggers",
             "schedule": 60.0,
@@ -184,6 +195,16 @@ def _mail_delivery_outbox() -> MailDeliveryOutboxProvider | None:
     return capability
 
 
+def _mail_bounce_processing() -> MailBounceProcessingProvider | None:
+    registry = _platform_registry()
+    if not registry.has_capability(CAPABILITY_MAIL_BOUNCE_PROCESSING):
+        return None
+    capability = registry.require_capability(CAPABILITY_MAIL_BOUNCE_PROCESSING)
+    if not isinstance(capability, MailBounceProcessingProvider):
+        raise RuntimeError("Mail bounce-processing capability is invalid")
+    return capability
+
+
 def _dataflow_trigger_dispatcher(
     registry: PlatformRegistry | None = None,
 ) -> DataflowTriggerDispatcher | None:
@@ -357,6 +378,30 @@ def purge_mail_outbox(self, limit: int = 250):
         return dict(provider.purge_expired(session, limit=limit))
 
 
+@celery.task(name="govoplan.mail.scan_bounces", bind=True, max_retries=0)
+def scan_mail_bounces(
+    self,
+    tenant_id: str | None = None,
+    limit: int = 250,
+):
+    """Read configured DSN folders without mutating provider mailbox flags."""
+
+    from govoplan_core.db.session import get_database
+
+    with get_database().SessionLocal() as session:
+        provider = _mail_bounce_processing()
+        if provider is None:
+            return {
+                "sources": 0,
+                "processed_messages": 0,
+                "observations": 0,
+                "failures": [],
+            }
+        result = dict(provider.scan_due(session, tenant_id=tenant_id, limit=limit))
+        session.commit()
+        return result
+
+
 @celery.task(name="govoplan.calendar.dispatch_outbox", bind=True, max_retries=0)
 def dispatch_calendar_outbox(self, tenant_id: str | None = None, limit: int = 50):
     """Drain durable Calendar operations; retry timing lives in the database."""