TangibleInc
diff --git a/‎.github/workflows/phpunit.yml‎
Lines changed: 2 additions & 2 deletions b/‎.github/workflows/phpunit.yml‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎composer.lock‎
Lines changed: 188 additions & 1 deletion b/‎composer.lock‎
Lines changed: 188 additions & 1 deletion
diff --git a/‎ddd-src/Application/EventHandlers/AsyncWordPressActionHandler.php‎
Lines changed: 6 additions & 1 deletion b/‎ddd-src/Application/EventHandlers/AsyncWordPressActionHandler.php‎
Lines changed: 6 additions & 1 deletion
diff --git a/‎ddd-src/Application/EventHandlers/IntegrationListener.php‎
Lines changed: 32 additions & 0 deletions b/‎ddd-src/Application/EventHandlers/IntegrationListener.php‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎ddd-src/Application/Events/EventRouter.php‎
Lines changed: 5 additions & 5 deletions b/‎ddd-src/Application/Events/EventRouter.php‎
Lines changed: 5 additions & 5 deletions
diff --git a/‎ddd-src/Application/Events/EventsUnitOfWork.php‎
Lines changed: 4 additions & 0 deletions b/‎ddd-src/Application/Events/EventsUnitOfWork.php‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎ddd-src/Application/Events/TransportEnvelope.php‎
Lines changed: 43 additions & 0 deletions b/‎ddd-src/Application/Events/TransportEnvelope.php‎
Lines changed: 43 additions & 0 deletions
@@ -2,9 +2,9 @@ name: PHPUnit tests
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, v3-ddd, 'release/**' ]
   pull_request:
-    branches: [ master ]
+    branches: [ master, v3-ddd, 'release/**' ]
 
 jobs:
   test:
 
@@ -49,3 +49,4 @@ htmlcov/
 # Claude session scratch
 .claude/worktrees/
 .playwright-cli/
+.superpowers/
@@ -3,9 +3,14 @@
 namespace TangibleDDD\Application\EventHandlers;
 
 /**
+ * @deprecated 0.2.0 — the "async domain handler" is a category error (the AS hop
+ * is another TIME, not another thread; serialization forces params into
+ * record-land regardless of intent). Decompose into an IntegrationListener
+ * (the policy) + a Command (the work, under command_audit). Removal: 0.3.0.
+ *
  * Event handler that automatically queues the actual handling
  * to run asynchronously via Action Scheduler.
- * 
+ *
  * When the domain event fires, it enqueues an async action.
  * The actual handle() method runs in a separate request.
  */
 
@@ -0,0 +1,32 @@
+<?php
+
+namespace TangibleDDD\Application\EventHandlers;
+
+use TangibleDDD\Application\Commands\ICommand;
+use TangibleDDD\Domain\Events\IIntegrationEvent;
+
+/**
+ * A stateless automation policy: "whenever [fact], then [intention]."
+ *
+ * The whole job is get_command() — fact in, intention out, null = not my
+ * business. All work belongs in the command's handler (audit, retry,
+ * causation); a listener only translates. Auto-wired by namespace convention
+ * \Application\IntegrationListeners\ (eager boot constructs via the container,
+ * so ctor injection is available to subclasses that need it — the happy path
+ * needs nothing).
+ */
+abstract class IntegrationListener {
+
+  /** @return class-string<IIntegrationEvent> */
+  abstract protected function get_event_class(): string;
+
+  /** Fact in, intention out. Null = no reaction. */
+  abstract protected function get_command(IIntegrationEvent $event): ?ICommand;
+
+  public function __construct() {
+    \TangibleDDD\WordPress\integration_listener(
+      static::get_event_class(),
+      fn(IIntegrationEvent $event) => $this->get_command($event)
+    );
+  }
+}
@@ -2,14 +2,14 @@
 
 namespace TangibleDDD\Application\Events;
 
+use TangibleDDD\Domain\Events\IAnnouncesIntegration;
 use TangibleDDD\Domain\Events\IDomainEvent;
-use TangibleDDD\Domain\Events\IIntegrationEvent;
 
 /**
  * Routes domain events to appropriate destinations.
  *
- * 1. All domain events go to the dispatcher (WordPress hooks)
- * 2. Integration events additionally go to the bus (outbox)
+ * 1. All domain events go to the dispatcher (WordPress hooks).
+ * 2. Announcing events additionally send their record to the bus.
  */
 final class EventRouter {
   public function __construct(
@@ -20,8 +20,8 @@ public function __construct(
   public function publish(IDomainEvent $event): void {
     $this->dispatcher->dispatch($event);
 
-    if ($event instanceof IIntegrationEvent) {
-      $this->bus->publish($event);
+    if ($event instanceof IAnnouncesIntegration) {
+      $this->bus->publish($event->to_integration());
     }
   }
 }
@@ -3,6 +3,7 @@
 namespace TangibleDDD\Application\Events;
 
 use TangibleDDD\Application\Exceptions\DomainEventAfterSealException;
+use TangibleDDD\Domain\Events\AlreadyIntegrated;
 use TangibleDDD\Domain\Events\IDomainEvent;
 use TangibleDDD\Domain\Events\IIntegrationEvent;
 use TangibleDDD\Domain\Shared\IRecordsDomainEvents;
@@ -41,6 +42,9 @@ public function seal(): void {
   }
 
   public function record(IDomainEvent $event): void {
+    if ($event instanceof IIntegrationEvent && $event->event_id() !== null) {
+      throw new AlreadyIntegrated(get_class($event), $event->event_id());
+    }
     if ($this->sealed && !$event instanceof IIntegrationEvent) {
       throw new DomainEventAfterSealException(get_class($event));
     }
 
@@ -0,0 +1,43 @@
+<?php
+
+namespace TangibleDDD\Application\Events;
+
+use TangibleDDD\Application\Correlation\CorrelationContext;
+
+/**
+ * The journey's wire form. OutboxProcessor smears __-keys into the payload bag
+ * for transport; this is the single place they are separated back out.
+ * Used by the WP integration_action() helper, the listener ceremony, and the
+ * process runner's wake path.
+ */
+final class TransportEnvelope {
+
+  private function __construct(
+    public readonly array $payload,
+    public readonly ?string $correlation_id,
+    public readonly ?int $sequence,
+    public readonly ?string $event_id,
+  ) {}
+
+  public static function unwrap(array $wrapped): self {
+    $correlation_id = isset($wrapped['__correlation_id']) ? (string) $wrapped['__correlation_id'] : null;
+    $sequence = isset($wrapped['__sequence']) ? (int) $wrapped['__sequence'] : null;
+    $event_id = isset($wrapped['__event_id']) ? (string) $wrapped['__event_id'] : null;
+    unset($wrapped['__correlation_id'], $wrapped['__sequence'], $wrapped['__event_id']);
+
+    return new self($wrapped, $correlation_id, $sequence, $event_id);
+  }
+
+  /** Restore ambient correlation + stash this event as causation for dispatched commands. */
+  public function restore_context(): void {
+    if ($this->correlation_id !== null) {
+      CorrelationContext::init($this->correlation_id);
+    }
+    if ($this->sequence !== null) {
+      CorrelationContext::set_sequence($this->sequence);
+    }
+    if ($this->event_id !== null) {
+      CorrelationContext::set_causation($this->event_id, 'integration_event');
+    }
+  }
+}
Original file line number	Diff line number	Diff line change
`@@ -2,14 +2,14 @@`
`2`	`2`
`3`	`3`	`namespace TangibleDDD\Application\Events;`
`4`	`4`
	`5`	`+use TangibleDDD\Domain\Events\IAnnouncesIntegration;`
`5`	`6`	`use TangibleDDD\Domain\Events\IDomainEvent;`
`6`		`-use TangibleDDD\Domain\Events\IIntegrationEvent;`
`7`	`7`
`8`	`8`	`/**`
`9`	`9`	`* Routes domain events to appropriate destinations.`
`10`	`10`	`*`
`11`		`- * 1. All domain events go to the dispatcher (WordPress hooks)`
`12`		`- * 2. Integration events additionally go to the bus (outbox)`
	`11`	`+ * 1. All domain events go to the dispatcher (WordPress hooks).`
	`12`	`+ * 2. Announcing events additionally send their record to the bus.`
`13`	`13`	`*/`
`14`	`14`	`final class EventRouter {`
`15`	`15`	`public function __construct(`
`@@ -20,8 +20,8 @@ public function __construct(`
`20`	`20`	`public function publish(IDomainEvent $event): void {`
`21`	`21`	`$this->dispatcher->dispatch($event);`
`22`	`22`
`23`		`- if ($event instanceof IIntegrationEvent) {`
`24`		`- $this->bus->publish($event);`
	`23`	`+ if ($event instanceof IAnnouncesIntegration) {`
	`24`	`+ $this->bus->publish($event->to_integration());`
`25`	`25`	`}`
`26`	`26`	`}`
`27`	`27`	`}`