release: v1.0.4

src/Kernel/ContextResponseInterface.php

@@ -32,16 +32,19 @@ public function setData(array $data): self;
     public function getData(): array;
 
     /**
-     * Add a domain event.
+     * Add an event, classified by its publication scope.
      */
-    public function addEvent(object $event): self;
+    public function addEvent(object $event, EventScope $scope = EventScope::Internal): self;
 
     /**
      * Get events from this result, keyed by context name.
      *
+     * Without a scope, returns all events (structurally unchanged). With a
+     * scope, returns only the events of that scope.
+     *
      * @return array<string, array<int, object>>
      */
-    public function getEvents(): array;
+    public function getEvents(?EventScope $scope = null): array;
 
     /**
      * Add an error message.

src/Kernel/DomainResponseInterface.php

@@ -32,9 +32,12 @@ public function getData(): array;
     /**
      * Get all collected domain events, keyed by context name.
      *
+     * Without a scope, returns all events (structurally unchanged). With a
+     * scope, returns only the events of that scope.
+     *
      * @return array<string, array<int, object>>
      */
-    public function getEvents(): array;
+    public function getEvents(?EventScope $scope = null): array;
 
     /**
      * Get all errors, keyed by context name.

src/Kernel/EventScope.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JardisSupport\Contract\Kernel;
+
+/**
+ * Classifies a collected event by its publication scope.
+ *
+ * Used as the write-gesture on ContextResponseInterface::addEvent() to
+ * distinguish aggregate-internal events from events that are announced
+ * outside the system.
+ */
+enum EventScope: string
+{
+    case Internal = 'internal';   // aggregate-level, stays within the system
+    case Domain = 'domain';       // announced, leaves the system
+}