we are writing Bitcoin baby

Author: titustangible

ddd-src/Application/Process/LongProcess.php

@@ -3,7 +3,6 @@
 namespace TangibleDDD\Application\Process;
 
 use DateTimeImmutable;
-use TangibleDDD\Domain\Events\IIntegrationEvent;
 use TangibleDDD\Domain\Shared\Aggregate;
 use TangibleDDD\Domain\Shared\JsonLifecycleValue;
 
@@ -13,47 +12,54 @@
  * Processes are defined as a series of steps (methods) that execute in declaration order.
  * Each step returns a Result that tells the runner what to do next:
  * - payload: pass data to the next step (must be JsonLifecycleValue)
- * - queries: execute these queries, pass results to next step
- * - commands: execute these commands (they send() themselves)
+ * - commands: execute these commands (fire-and-forget side effects)
  * - await: suspend until an integration event fires
  *
+ * ## Step Signatures
+ *
+ * Steps can have different signatures depending on what they need:
+ * - `protected function step_name(): Result` - no input needed
+ * - `protected function step_name(SomePayload $payload): Result` - receives payload
+ * - `protected function step_name(?SomePayload $payload, SomeEvent $event): Result` - post-await step
+ *
  * ## 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:
+ * App\Process\OrderFulfillmentProcess:
  *   tags:
  *     - name: 'ddd.long_process'
  *       awaits:
- *         - App\Events\UserApprovedPath
+ *         - App\Events\PaymentReceived
  * ```
  *
  * ## Example
  *
  * ```php
- * class GenerateLearningPath extends LongProcess {
+ * class OrderFulfillmentProcess extends LongProcess {
  *   public function __construct(
- *     private readonly int $user_id,
+ *     private readonly int $order_id,
  *   ) {
  *     parent::__construct(null);
  *   }
  *
- *   protected function fetch_history(): Result {
- *     return new Result(payload: new HistoryPayload($this->user_id));
+ *   protected function initialize(): Result {
+ *     return new Result(payload: new OrderPayload($this->order_id));
  *   }
  *
- *   protected function request_approval(HistoryPayload $payload): Result {
+ *   protected function request_payment(OrderPayload $payload): Result {
+ *     // Dispatch payment request...
  *     return new Result(
- *       await: new AwaitEvent(UserApprovedPath::class, ['user_id' => $this->user_id])
+ *       payload: $payload,
+ *       await: new AwaitEvent(PaymentReceived::class, ['order_id' => $this->order_id])
  *     );
  *   }
  *
- *   // Next step receives the event via $this->resume_event()
- *   protected function process_approval(): Result {
- *     $event = $this->resume_event(UserApprovedPath::class);
- *     // ... use event data
+ *   // Post-await step receives both payload and the event that woke it
+ *   protected function process_payment(?OrderPayload $payload, PaymentReceived $event): Result {
+ *     // Use $event->amount, $event->transaction_id, etc.
  *     return new Result();
  *   }
  * }
@@ -85,17 +91,6 @@ 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)
   // ─────────────────────────────────────────────────────────────────────────
@@ -132,50 +127,6 @@ 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)
   // ─────────────────────────────────────────────────────────────────────────

ddd-src/Application/Process/ProcessRunner.php

@@ -16,7 +16,7 @@
  * Responsibilities:
  * - Register event types for process resume
  * - Discover steps via reflection (methods in declaration order)
- * - Execute steps and dispatch returned commands/queries
+ * - Execute steps and dispatch returned commands
  * - Suspend on AwaitEvent and persist state
  * - Resume when matching integration event fires
  * - Reschedule via ActionScheduler when resources exhausted or #[Async] step
@@ -30,6 +30,9 @@ final class ProcessRunner {
   /** @var array<string, bool> Tracks which events have action hooks registered */
   private array $registered_events = [];
 
+  /** @var IIntegrationEvent|null Transient - event that triggered current resume */
+  private ?IIntegrationEvent $resume_event = null;
+
   public function __construct(
     private readonly IDDDConfig $config,
     private readonly IProcessRepository $repository,
@@ -134,12 +137,15 @@ public function resume_on_event(IIntegrationEvent $event): void {
 
       // The awaited event arrived - complete the waiting step and move forward
       $process->advance_step();
-      $process->set_resume_event($event);
+      $this->resume_event = $event; // Store for next step to receive
       $process->advance(status: 'running', payload: $process->payload());
       $this->repository->save($process);
 
       $this->run($process);
 
+      // Clear transient state
+      $this->resume_event = null;
+
       // Only resume first matching process per event
       // (if you need fan-out, remove this return)
       return;
@@ -204,7 +210,7 @@ private function execute_forward(LongProcess $process): void {
           );
         }
 
-        $this->dispatch_side_effects($result);
+        $this->dispatch_commands($result);
 
         // Check for event-based suspension
         if ($result->should_suspend()) {
@@ -218,7 +224,7 @@ private function execute_forward(LongProcess $process): void {
         // Advance to next step
         $process->advance_step();
         $process->advance(status: 'running', payload: $result->payload);
-        $process->clear_resume_event();
+        $this->resume_event = null; // Clear after first step post-resume
         $this->repository->save($process);
 
         // Check resources after each step
@@ -283,7 +289,7 @@ private function execute_compensation(LongProcess $process): void {
         $checkpoint = $process->checkpoint_for($step_name);
         $result = $method->invoke($process, $cause, $checkpoint);
 
-        $this->dispatch_side_effects($result);
+        $this->dispatch_commands($result);
 
         if ($result->should_suspend()) {
           $this->suspend_for_event($process, $result);
@@ -318,25 +324,32 @@ private function execute_compensation(LongProcess $process): void {
 
   /**
    * Execute a single step method.
+   *
+   * Supports three signatures:
+   * - step(): Result - no params
+   * - step($payload): Result - receives payload
+   * - step($payload, $event): Result - receives payload + event (post-await)
    */
   private function execute_step(LongProcess $process, ReflectionMethod $step): mixed {
     $params = $step->getParameters();
+    $param_count = count($params);
 
-    if (empty($params)) {
+    if ($param_count === 0) {
       return $step->invoke($process);
     }
 
-    return $step->invoke($process, $process->payload());
+    if ($param_count === 1) {
+      return $step->invoke($process, $process->payload());
+    }
+
+    // 2+ params: pass payload and event
+    return $step->invoke($process, $process->payload(), $this->resume_event);
   }
 
   /**
-   * Dispatch commands and queries from a Result.
+   * Dispatch commands from a Result (fire-and-forget side effects).
    */
-  private function dispatch_side_effects(Result $result): void {
-    foreach ($result->queries as $query) {
-      $query->send();
-    }
-
+  private function dispatch_commands(Result $result): void {
     foreach ($result->commands as $command) {
       $command->send();
     }

ddd-src/Application/Process/Result.php

@@ -9,10 +9,12 @@
  *
  * Each step returns a Result that tells the runner what to do:
  * - payload: pass data to the next step (must be JsonLifecycleValue)
- * - queries: execute these queries, pass results to next step
- * - commands: execute these commands
+ * - commands: execute these commands (fire-and-forget side effects)
  * - await: suspend until this event fires
  * - checkpoint: data for compensation (must be JsonLifecycleValue)
+ *
+ * Steps that need to query for data should do so directly within the step
+ * method, then return the relevant data in the payload.
  */
 final class Result {
   public function __construct(
@@ -22,10 +24,7 @@ public function __construct(
      */
     public readonly ?JsonLifecycleValue $payload = null,
 
-    /** @var array Queries to execute (results passed to next step) */
-    public readonly array $queries = [],
-
-    /** @var array Commands to dispatch */
+    /** @var array Commands to dispatch (fire-and-forget) */
     public readonly array $commands = [],
 
     /** Suspend and wait for this event */
@@ -39,10 +38,6 @@ public function __construct(
     public readonly ?JsonLifecycleValue $checkpoint = null,
   ) {}
 
-  public function has_queries(): bool {
-    return !empty($this->queries);
-  }
-
   public function has_commands(): bool {
     return !empty($this->commands);
   }