#300: add Workflow::now() — deterministic workflow time

WorkflowFiberContext: stores per-fiber deterministic time, set by
the executor from history event timestamps before resuming.

WorkflowExecutor: syncWorkflowCursor accepts optional eventTime and
updates the fiber context. Initial time set from run started_at.

Workflow::now() and Workflow\V2\now() expose the deterministic time.
Outside a workflow fiber, falls back to wall-clock now().

Author: durable-workflow-ops

src/V2/Support/WorkflowExecutor.php

@@ -97,7 +97,7 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
         $current = $workflowExecution->current();
 
         $sequence = 1;
-        $this->syncWorkflowCursor($workflow, $sequence);
+        $this->syncWorkflowCursor($workflow, $sequence, $run->started_at);
         $historySequenceAtTaskStart = $run->last_history_sequence ?? 0;
 
         while (true) {
@@ -116,7 +116,7 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
 
             if (! $workflowExecution->valid()) {
                 try {
-                    $this->syncWorkflowCursor($workflow, $sequence);
+                    $this->syncWorkflowCursor($workflow, $sequence, $run->started_at);
                     $this->completeRun($run, $task, $workflowExecution->getReturn());
                 } catch (Throwable $throwable) {
                     $this->failRun($run, $task, $throwable, 'workflow_run', $run->id);
@@ -862,7 +862,7 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
 
                 if ($groupSize === 0) {
                     try {
-                        $this->syncWorkflowCursor($workflow, $sequence);
+                        $this->syncWorkflowCursor($workflow, $sequence, $run->started_at);
                         $current = $workflowExecution->send($current->nestedResults([]));
                     } catch (Throwable $throwable) {
                         $this->failRun($run, $task, $throwable, 'workflow_run', $run->id);
@@ -3942,7 +3942,7 @@ private function cancelSignalTimeout(WorkflowRun $run, WorkflowTask $task, Workf
         $this->cancelConditionTimeout($run, $task, $timer);
     }
 
-    private function syncWorkflowCursor(Workflow $workflow, int $visibleSequence): void
+    private function syncWorkflowCursor(Workflow $workflow, int $visibleSequence, ?\Carbon\CarbonInterface $eventTime = null): void
     {
         $workflow->syncExecutionCursor($visibleSequence);
         $workflow->setCommandDispatchEnabled(true);

src/V2/Support/WorkflowFiberContext.php

@@ -4,6 +4,7 @@
 
 namespace Workflow\V2\Support;
 
+use Carbon\CarbonInterface;
 use Fiber;
 use LogicException;
 
@@ -14,6 +15,14 @@ final class WorkflowFiberContext
      */
     private static array $activeFibers = [];
 
+    /**
+     * Deterministic workflow time per fiber, set by the executor from the
+     * latest history event recorded_at before resuming the workflow.
+     *
+     * @var array<int, CarbonInterface>
+     */
+    private static array $workflowTime = [];
+
     public static function enter(): void
     {
         $fiber = Fiber::getCurrent();
@@ -34,6 +43,7 @@ public static function leave(): void
         }
 
         unset(self::$activeFibers[spl_object_id($fiber)]);
+        unset(self::$workflowTime[spl_object_id($fiber)]);
     }
 
     public static function active(): bool
@@ -47,6 +57,36 @@ public static function active(): bool
         return isset(self::$activeFibers[spl_object_id($fiber)]);
     }
 
+    /**
+     * Set the deterministic workflow time for the current fiber.
+     */
+    public static function setTime(CarbonInterface $time): void
+    {
+        $fiber = Fiber::getCurrent();
+
+        if ($fiber instanceof Fiber) {
+            self::$workflowTime[spl_object_id($fiber)] = $time;
+        }
+    }
+
+    /**
+     * Read the deterministic workflow time for the current fiber.
+     *
+     * Returns the timestamp of the last history event the executor replayed
+     * before resuming this fiber. Outside a workflow context, falls back to
+     * wall-clock time via now().
+     */
+    public static function getTime(): CarbonInterface
+    {
+        $fiber = Fiber::getCurrent();
+
+        if ($fiber instanceof Fiber && isset(self::$workflowTime[spl_object_id($fiber)])) {
+            return self::$workflowTime[spl_object_id($fiber)];
+        }
+
+        return now();
+    }
+
     public static function suspend(mixed $call): mixed
     {
         if (! self::active()) {

src/V2/Workflow.php

@@ -190,6 +190,19 @@ public function setCommandDispatchEnabled(bool $enabled): void
     // These are pure delegates. Behaviour, determinism guarantees, and
     // operand/return types come from the underlying helper functions.
 
+    /**
+     * Read the deterministic workflow time.
+     *
+     * Inside a workflow fiber, returns the timestamp of the last history
+     * event the executor replayed. Outside a workflow, returns wall-clock.
+     *
+     * @see \Workflow\V2\now()
+     */
+    public static function now(): \Carbon\CarbonInterface
+    {
+        return \Workflow\V2\Support\WorkflowFiberContext::getTime();
+    }
+
     /**
      * Invoke an activity and wait for its result.
      *

src/V2/functions.php

@@ -268,3 +268,17 @@ function years(int $years): mixed
         return timer("{$years} years");
     }
 }
+
+if (! function_exists(__NAMESPACE__ . '\\now')) {
+    /**
+     * Read the deterministic workflow time.
+     *
+     * Inside a workflow fiber, returns the timestamp of the last history
+     * event the executor replayed before resuming.
+     * Outside a workflow fiber, falls back to wall-clock time.
+     */
+    function now(): \Carbon\CarbonInterface
+    {
+        return WorkflowFiberContext::getTime();
+    }
+}