Define governed platform event envelope

tests/test_core_events.py

@@ -9,7 +9,16 @@ from fastapi import APIRouter
 from fastapi.testclient import TestClient
 
 from govoplan_core.audit.logging import audit_event, audit_operation_context
-from govoplan_core.core.events import EventBus, PlatformEvent, current_event_trace, event_context, normalize_trace_id
+from govoplan_core.core.events import (
+    EventActorRef,
+    EventBus,
+    EventObjectRef,
+    EventTenantRef,
+    PlatformEvent,
+    current_event_trace,
+    event_context,
+    normalize_trace_id,
+)
 from govoplan_core.core.registry import PlatformRegistry
 from govoplan_core.db.base import Base
 from govoplan_core.server.fastapi import create_govoplan_app
@@ -37,6 +46,60 @@ class CoreEventTests(unittest.TestCase):
         self.assertEqual("corr-1", child.correlation_id)
         self.assertEqual(parent.event_id, child.causation_id)
 
+    def test_platform_event_serializes_governed_envelope_fields(self) -> None:
+        event = PlatformEvent(
+            type="case.permit.updated",
+            module_id="cases",
+            payload={"status": "approved"},
+            event_id="event-1",
+            correlation_id="corr-1",
+            causation_id="cause-1",
+            actor=EventActorRef(type="user", id="user-1", label="Case worker"),
+            tenant=EventTenantRef(id="tenant-1", slug="city", label="City Office"),
+            subject=EventObjectRef(type="person", id="person-1", label="Applicant"),
+            resource=EventObjectRef(type="permit", id="permit-1", label="Permit"),
+            classification="confidential",
+        )
+
+        payload = event.to_dict()
+
+        self.assertEqual("case.permit.updated", payload["type"])
+        self.assertEqual("cases", payload["module_id"])
+        self.assertEqual({"status": "approved"}, payload["payload"])
+        self.assertEqual("event-1", payload["event_id"])
+        self.assertEqual("corr-1", payload["correlation_id"])
+        self.assertEqual("cause-1", payload["causation_id"])
+        self.assertEqual({"type": "user", "id": "user-1", "label": "Case worker"}, payload["actor"])
+        self.assertEqual({"id": "tenant-1", "slug": "city", "label": "City Office"}, payload["tenant"])
+        self.assertEqual({"type": "person", "id": "person-1", "label": "Applicant"}, payload["subject"])
+        self.assertEqual({"type": "permit", "id": "permit-1", "label": "Permit"}, payload["resource"])
+        self.assertEqual("confidential", payload["classification"])
+
+    def test_event_bus_preserves_envelope_fields_when_adding_trace(self) -> None:
+        bus = EventBus()
+        seen: list[PlatformEvent] = []
+        event = PlatformEvent(
+            type="files.file.uploaded",
+            module_id="files",
+            actor=EventActorRef(type="api_key", id="key-1"),
+            tenant=EventTenantRef(id="tenant-1"),
+            subject=EventObjectRef(type="file", id="file-1"),
+            resource=EventObjectRef(type="folder", id="folder-1"),
+            classification="restricted",
+        )
+
+        bus.subscribe("files.file.uploaded", seen.append)
+        bus.publish(event)
+
+        self.assertEqual(1, len(seen))
+        traced = seen[0]
+        self.assertIsNotNone(traced.correlation_id)
+        self.assertEqual(event.actor, traced.actor)
+        self.assertEqual(event.tenant, traced.tenant)
+        self.assertEqual(event.subject, traced.subject)
+        self.assertEqual(event.resource, traced.resource)
+        self.assertEqual("restricted", traced.classification)
+
     def test_request_correlation_middleware_sets_event_context_and_response_header(self) -> None:
         router = APIRouter()