Add durable platform event delivery contract

src/govoplan_core/core/events.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Mapping, Sequence
 from contextlib import contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass, field
@@ -15,6 +15,7 @@ from sqlalchemy.orm import Session
 
 
 _TRACE_ID_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,128}$")
+_CONSUMER_ID_RE = re.compile(r"^[a-z][a-z0-9_.:-]{0,127}$")
 _PENDING_EVENTS_KEY = "govoplan.pending_platform_events"
 CAPABILITY_PLATFORM_EVENT_OUTBOX = "platform.eventOutbox"
 
@@ -105,6 +106,63 @@ class PlatformEvent:
 
 
 EventHandler = Callable[[PlatformEvent], None]
+DurableEventHandler = Callable[[PlatformEvent, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class DurableEventConsumer:
+    """Allowlisted durable consumer with an explicit disclosure boundary."""
+
+    consumer_id: str
+    handler: DurableEventHandler
+    event_types: frozenset[str] = field(
+        default_factory=lambda: frozenset({"*"})
+    )
+    classifications: frozenset[EventClassification] = field(
+        default_factory=lambda: frozenset({"public", "internal"})
+    )
+    policy_decision_ref: str | None = None
+
+    def __post_init__(self) -> None:
+        if not _CONSUMER_ID_RE.fullmatch(self.consumer_id):
+            raise ValueError("Durable event consumer id is invalid")
+        if not self.event_types or any(
+            item != "*" and not _TRACE_ID_RE.fullmatch(item)
+            for item in self.event_types
+        ):
+            raise ValueError(
+                "Durable event consumers require valid event-type allowlists"
+            )
+        invalid_classifications = set(self.classifications) - {
+            "public",
+            "internal",
+            "confidential",
+            "restricted",
+        }
+        if not self.classifications or invalid_classifications:
+            raise ValueError(
+                "Durable event consumer classifications are invalid"
+            )
+        if (
+            self.classifications & {"confidential", "restricted"}
+            and not normalize_trace_id(self.policy_decision_ref)
+        ):
+            raise ValueError(
+                "Confidential or restricted event subscriptions require "
+                "an explicit policy decision reference"
+            )
+
+    def accepts(self, event: PlatformEvent) -> bool:
+        return (
+            event.classification in self.classifications
+            and (
+                "*" in self.event_types
+                or event.type in self.event_types
+            )
+        )
+
+    def delivery_key(self, event: PlatformEvent) -> str:
+        return f"{event.event_id}:{self.consumer_id}"
 
 
 @runtime_checkable
@@ -116,11 +174,38 @@ class PlatformEventOutbox(Protocol):
         self,
         session: object,
         *,
-        dispatcher: EventHandler,
+        consumers: Sequence[DurableEventConsumer] = (),
+        observer: EventHandler | None = None,
         limit: int = 100,
     ) -> Mapping[str, int]:
         ...
 
+    def replay_delivery(
+        self,
+        session: object,
+        *,
+        event_id: str,
+        consumer_id: str,
+        operator_id: str,
+        reason: str,
+    ) -> Mapping[str, object]:
+        ...
+
+    def purge_terminal(
+        self,
+        session: object,
+        *,
+        before: datetime,
+        limit: int = 500,
+    ) -> Mapping[str, int]:
+        ...
+
+    def delivery_metrics(
+        self,
+        session: object,
+    ) -> Mapping[str, object]:
+        ...
+
 
 def current_event_trace() -> EventTrace | None:
     return _current_trace.get()

src/govoplan_core/core/install_config.py

@@ -338,8 +338,10 @@ ENABLED_MODULES=tenancy,organizations,identity,access,admin,dashboard,policy,aud
 
 CELERY_ENABLED=true
 REDIS_URL=redis://127.0.0.1:6379/0
-CELERY_QUEUES=send_email,append_sent,notifications,calendar,default
+CELERY_QUEUES=send_email,append_sent,notifications,calendar,dataflow,events,default
 CALENDAR_OUTBOX_TERMINAL_RETENTION_DAYS=90
+PLATFORM_EVENT_OUTBOX_MAX_ATTEMPTS=8
+PLATFORM_EVENT_OUTBOX_TERMINAL_RETENTION_DAYS=90
 SCHEDULING_CANCELLATION_NOTICE_DAYS=30
 
 # Deployment-wide connector egress policy. Enable private networks only when
@@ -404,8 +406,10 @@ DATABASE_URL=postgresql+psycopg://govoplan:govoplan-dev@127.0.0.1:55433/govoplan
 GOVOPLAN_DATABASE_URL_PGTOOLS=postgresql://govoplan:govoplan-dev@127.0.0.1:55433/govoplan
 REDIS_URL=redis://127.0.0.1:56379/0
 CELERY_ENABLED=true
-CELERY_QUEUES=send_email,append_sent,notifications,calendar,default
+CELERY_QUEUES=send_email,append_sent,notifications,calendar,dataflow,events,default
 CALENDAR_OUTBOX_TERMINAL_RETENTION_DAYS=90
+PLATFORM_EVENT_OUTBOX_MAX_ATTEMPTS=8
+PLATFORM_EVENT_OUTBOX_TERMINAL_RETENTION_DAYS=90
 SCHEDULING_CANCELLATION_NOTICE_DAYS=30
 
 GOVOPLAN_CONNECTOR_ALLOW_PRIVATE_NETWORKS=true