declarative wakeup of long processes based on DI

Author: titustangible

ddd-src/Application/Process/AwaitEvent.php

@@ -10,6 +10,22 @@
  *
  * When a step returns Result with an AwaitEvent, the process suspends
  * and resumes when a matching event is published.
+ *
+ * IMPORTANT: Any event class used with AwaitEvent must be declared in the
+ * process's DI service tag so the framework can wire up the action hooks.
+ *
+ * In your services.yaml:
+ * ```yaml
+ * App\Process\OrderFulfillmentProcess:
+ *   tags:
+ *     - name: 'ddd.long_process'
+ *       awaits:
+ *         - App\Events\PaymentReceived
+ *         - App\Events\UserApproved
+ * ```
+ *
+ * If you forget to declare an awaited event, the process will suspend
+ * but never resume (the action hook won't be registered).
  */
 final class AwaitEvent {
   /** @var class-string<IIntegrationEvent> */

ddd-src/Application/Process/LongProcess.php

@@ -3,6 +3,7 @@
 namespace TangibleDDD\Application\Process;
 
 use DateTimeImmutable;
+use TangibleDDD\Domain\Events\IIntegrationEvent;
 use TangibleDDD\Domain\Shared\Aggregate;
 use TangibleDDD\Domain\Shared\JsonLifecycleValue;
 
@@ -16,7 +17,21 @@
  * - commands: execute these commands (they send() themselves)
  * - await: suspend until an integration event fires
  *
- * Example:
+ * ## DI Registration
+ *
+ * Register your process in services.yaml with the 'ddd.long_process' tag.
+ * If your process uses AwaitEvent, declare the awaited event classes:
+ *
+ * ```yaml
+ * App\Process\GenerateLearningPath:
+ *   tags:
+ *     - name: 'ddd.long_process'
+ *       awaits:
+ *         - App\Events\UserApprovedPath
+ * ```
+ *
+ * ## Example
+ *
  * ```php
  * class GenerateLearningPath extends LongProcess {
  *   public function __construct(
@@ -34,6 +49,13 @@
  *       await: new AwaitEvent(UserApprovedPath::class, ['user_id' => $this->user_id])
  *     );
  *   }
+ *
+ *   // Next step receives the event via $this->resume_event()
+ *   protected function process_approval(): Result {
+ *     $event = $this->resume_event(UserApprovedPath::class);
+ *     // ... use event data
+ *     return new Result();
+ *   }
  * }
  * ```
  */
@@ -63,6 +85,17 @@ abstract class LongProcess extends Aggregate {
    */
   protected ?ProcessSteps $steps = null;
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Transient state (NOT persisted - only valid during current execution)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Event that triggered resume from suspension.
+   * Available to the step immediately after an await.
+   * Cleared after the step executes.
+   */
+  private ?IIntegrationEvent $resume_event = null;
+
   // ─────────────────────────────────────────────────────────────────────────
   // Accessors (framework state)
   // ─────────────────────────────────────────────────────────────────────────
@@ -99,6 +132,50 @@ public function updated_at(): ?DateTimeImmutable {
     return $this->updated_at;
   }
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Transient state accessors
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the event that triggered resume from suspension.
+   * Only available to the step immediately after an await.
+   *
+   * @template T of IIntegrationEvent
+   * @param class-string<T>|null $expected_class Optional type check
+   * @return T|IIntegrationEvent|null
+   */
+  public function resume_event(?string $expected_class = null): ?IIntegrationEvent {
+    if ($this->resume_event === null) {
+      return null;
+    }
+
+    if ($expected_class !== null && !($this->resume_event instanceof $expected_class)) {
+      throw new \RuntimeException(sprintf(
+        'Expected resume event of type %s, got %s',
+        $expected_class,
+        get_class($this->resume_event)
+      ));
+    }
+
+    return $this->resume_event;
+  }
+
+  /**
+   * Set the resume event (called by ProcessRunner).
+   * @internal
+   */
+  public function set_resume_event(IIntegrationEvent $event): void {
+    $this->resume_event = $event;
+  }
+
+  /**
+   * Clear the resume event after step execution.
+   * @internal
+   */
+  public function clear_resume_event(): void {
+    $this->resume_event = null;
+  }
+
   // ─────────────────────────────────────────────────────────────────────────
   // Step state accessors (delegates to ProcessSteps, hides internal structure)
   // ─────────────────────────────────────────────────────────────────────────