Add v2 patch marker workflow helpers

durable-workflow-ops · durable-workflow-ops · commit ec20a32e3c95 · 2026-04-21T17:18:18.000Z
Issue: zorporation/durable-workflow#446 Loop-ID: build-02
diff --git a/docs/api-stability.md b/docs/api-stability.md
@@ -87,7 +87,8 @@ guarantee:
   `Workflow\V2\functions.php`: `activity`, `executeActivity`, `child`,
   `executeChildWorkflow`, `async`, `all`, `parallel`, `await`,
   `awaitWithTimeout`, `awaitSignal`, `timer`, `sideEffect`,
-  `continueAsNew`, `getVersion`, `upsertMemo`, `upsertSearchAttributes`,
+  `continueAsNew`, `getVersion`, `patched`, `deprecatePatch`,
+  `upsertMemo`, `upsertSearchAttributes`,
   and the timer sugar `seconds`/`minutes`/`hours`/`days`/`weeks`/
   `months`/`years`.
 
@@ -117,14 +118,21 @@ the PHP class that produced the event is `@internal`.
 
 ### `VersionMarkerRecorded`
 
-This marker records the result of `Workflow::getVersion()` (PHP) and
-`workflow.get_version()` (Python SDK). The moment an operational
+This marker records the result of `Workflow::getVersion()`, `Workflow::patched()`,
+or `Workflow::deprecatePatch()` (PHP) and `workflow.get_version()`,
+`workflow.patched()`, or `workflow.deprecate_patch()` (Python SDK). The moment an operational
 workflow writes a `VersionMarkerRecorded` event, every replayer for
 the rest of that workflow's lifetime must continue to decode the same
 payload. See PHP `Workflow\V2\Support\DefaultWorkflowTaskBridge::applyRecordVersionMarker()`
 and Python `durable_workflow.workflow._workflow_state` for the
 authoritative emission and replay sites.
 
+`patched(change_id)` and `deprecatePatch(change_id)` / `deprecate_patch(change_id)`
+are additive sugar over this same frozen shape. They do not introduce a new
+event type: patched markers use `min_supported = -1`, `max_supported = 1`,
+and `version = 1`; replaying version `-1` means the workflow reached the patch
+site before the patch marker existed.
+
 **Payload shape — frozen:**
 
 | key             | type    | meaning                                   |
diff --git a/src/V2/Support/QueryStateReplayer.php b/src/V2/Support/QueryStateReplayer.php
@@ -235,7 +235,10 @@ public function replayState(WorkflowRun $run): ReplayState
                 $resolution = VersionResolver::resolve($run, $versionEvent, $current, $sequence);
 
                 $this->syncWorkflowCursor($workflow, $sequence + ($resolution->advancesSequence ? 1 : 0));
-                $current = $workflowExecution->send($resolution->version, $versionEvent?->recorded_at);
+                $current = $workflowExecution->send(
+                    $current->resolveValue($resolution->version),
+                    $versionEvent?->recorded_at
+                );
 
                 if ($resolution->advancesSequence) {
                     ++$sequence;
@@ -592,7 +595,7 @@ public function replayState(WorkflowRun $run): ReplayState
 
             $this->syncWorkflowCursor($workflow, $sequence);
             throw new UnsupportedWorkflowYieldException(sprintf(
-                'Workflow %s yielded %s. v2 currently supports activity(), child(), async(), all(), await(), signal(), timer(), sideEffect(), continueAsNew(), getVersion(), upsertMemo(), and upsertSearchAttributes() only.',
+                'Workflow %s yielded %s. v2 currently supports activity(), child(), async(), all(), await(), signal(), timer(), sideEffect(), continueAsNew(), getVersion(), patched(), deprecatePatch(), upsertMemo(), and upsertSearchAttributes() only.',
                 $run->workflow_class,
                 get_debug_type($current),
             ));
diff --git a/src/V2/Support/VersionCall.php b/src/V2/Support/VersionCall.php
@@ -6,13 +6,21 @@
 
 use LogicException;
 use Workflow\V2\Contracts\YieldedCommand;
+use Workflow\V2\WorkflowStub;
 
 final class VersionCall implements YieldedCommand
 {
+    public const RESULT_VERSION = 'version';
+
+    public const RESULT_PATCHED = 'patched';
+
+    public const RESULT_DEPRECATE_PATCH = 'deprecate_patch';
+
     public function __construct(
         public readonly string $changeId,
         public readonly int $minSupported,
         public readonly int $maxSupported,
+        public readonly string $resultKind = self::RESULT_VERSION,
     ) {
         if ($this->changeId === '') {
             throw new LogicException('V2 version change ids must be non-empty strings.');
@@ -26,5 +34,36 @@ public function __construct(
                 $this->maxSupported,
             ));
         }
+
+        if (! in_array($this->resultKind, [
+            self::RESULT_VERSION,
+            self::RESULT_PATCHED,
+            self::RESULT_DEPRECATE_PATCH,
+        ], true)) {
+            throw new LogicException(sprintf(
+                'V2 version change [%s] has unsupported result kind [%s].',
+                $this->changeId,
+                $this->resultKind,
+            ));
+        }
+    }
+
+    public static function patched(string $changeId): self
+    {
+        return new self($changeId, WorkflowStub::DEFAULT_VERSION, 1, self::RESULT_PATCHED);
+    }
+
+    public static function deprecatePatch(string $changeId): self
+    {
+        return new self($changeId, WorkflowStub::DEFAULT_VERSION, 1, self::RESULT_DEPRECATE_PATCH);
+    }
+
+    public function resolveValue(int $version): mixed
+    {
+        return match ($this->resultKind) {
+            self::RESULT_PATCHED => $version === 1,
+            self::RESULT_DEPRECATE_PATCH => null,
+            default => $version,
+        };
     }
 }
diff --git a/src/V2/Support/WorkflowExecutor.php b/src/V2/Support/WorkflowExecutor.php
@@ -487,7 +487,10 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
                     }
 
                     $this->syncWorkflowCursor($workflow, $sequence + ($resolution->advancesSequence ? 1 : 0));
-                    $current = $workflowExecution->send($version, $versionMarkerEvent?->recorded_at);
+                    $current = $workflowExecution->send(
+                        $current->resolveValue($version),
+                        $versionMarkerEvent?->recorded_at
+                    );
                 } catch (Throwable $throwable) {
                     $this->failRun($run, $task, $throwable, 'workflow_run', $run->id);
 
@@ -1307,7 +1310,7 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
                 $run,
                 $task,
                 new UnsupportedWorkflowYieldException(sprintf(
-                    'Workflow %s yielded %s. v2 currently supports activity(), child(), async(), all(), await(), signal(), timer(), sideEffect(), continueAsNew(), getVersion(), upsertMemo(), and upsertSearchAttributes() only.',
+                    'Workflow %s yielded %s. v2 currently supports activity(), child(), async(), all(), await(), signal(), timer(), sideEffect(), continueAsNew(), getVersion(), patched(), deprecatePatch(), upsertMemo(), and upsertSearchAttributes() only.',
                     $run->workflow_class,
                     get_debug_type($current),
                 )),
diff --git a/src/V2/Workflow.php b/src/V2/Workflow.php
@@ -350,6 +350,26 @@ public static function getVersion(
         return getVersion($changeId, $minSupported, $maxSupported);
     }
 
+    /**
+     * Return whether this workflow run has crossed a replay-safe code patch.
+     *
+     * @see patched()
+     */
+    public static function patched(string $changeId): mixed
+    {
+        return patched($changeId);
+    }
+
+    /**
+     * Keep a patch marker alive after the old workflow branch is removed.
+     *
+     * @see deprecatePatch()
+     */
+    public static function deprecatePatch(string $changeId): mixed
+    {
+        return deprecatePatch($changeId);
+    }
+
     /**
      * Upsert non-indexed memo metadata on the current workflow run.
      *
diff --git a/src/V2/functions.php b/src/V2/functions.php
@@ -224,6 +224,20 @@ function getVersion(
     }
 }
 
+if (! function_exists(__NAMESPACE__ . '\\patched')) {
+    function patched(string $changeId): mixed
+    {
+        return WorkflowFiberContext::suspend(VersionCall::patched($changeId));
+    }
+}
+
+if (! function_exists(__NAMESPACE__ . '\\deprecatePatch')) {
+    function deprecatePatch(string $changeId): mixed
+    {
+        return WorkflowFiberContext::suspend(VersionCall::deprecatePatch($changeId));
+    }
+}
+
 // Timer sugar
 
 if (! function_exists(__NAMESPACE__ . '\\seconds')) {
diff --git a/tests/Feature/V2/V2VersionWorkflowTest.php b/tests/Feature/V2/V2VersionWorkflowTest.php
@@ -5,6 +5,8 @@
 namespace Tests\Feature\V2;
 
 use Illuminate\Support\Facades\Queue;
+use Tests\Fixtures\V2\TestDeprecatedPatchWorkflow;
+use Tests\Fixtures\V2\TestPatchedWorkflow;
 use Tests\Fixtures\V2\TestVersionAfterSignalWorkflow;
 use Tests\Fixtures\V2\TestVersionBeforeSignalWorkflow;
 use Tests\Fixtures\V2\TestVersionMinSupportedWorkflow;
@@ -136,6 +138,95 @@ public function testVersionMarkersReuseRecordedHistoryValue(): void
         $this->assertSame('v2_result', $workflow->output()['result']);
     }
 
+    public function testPatchedRecordsMarkerAndResolvesTrueForCurrentRuns(): void
+    {
+        Queue::fake();
+
+        $workflow = WorkflowStub::make(TestPatchedWorkflow::class, 'patched-current');
+        $workflow->start();
+
+        $this->drainReadyTasks();
+
+        $this->assertTrue($workflow->refresh()->completed());
+        $this->assertSame([
+            'patched' => true,
+            'branch' => 'patched',
+        ], $workflow->output());
+
+        /** @var WorkflowHistoryEvent $marker */
+        $marker = WorkflowHistoryEvent::query()
+            ->where('workflow_run_id', $workflow->runId())
+            ->where('event_type', HistoryEventType::VersionMarkerRecorded->value)
+            ->firstOrFail();
+
+        $this->assertSame('patch-1', $marker->payload['change_id'] ?? null);
+        $this->assertSame(1, $marker->payload['version'] ?? null);
+        $this->assertSame(WorkflowStub::DEFAULT_VERSION, $marker->payload['min_supported'] ?? null);
+        $this->assertSame(1, $marker->payload['max_supported'] ?? null);
+    }
+
+    public function testPatchedResolvesFalseForRecordedLegacyMarker(): void
+    {
+        Queue::fake();
+
+        $workflow = WorkflowStub::make(TestPatchedWorkflow::class, 'patched-legacy');
+        $workflow->start();
+
+        /** @var WorkflowRun $run */
+        $run = WorkflowRun::query()->findOrFail($workflow->runId());
+
+        WorkflowHistoryEvent::query()->create([
+            'workflow_run_id' => $run->id,
+            'sequence' => 3,
+            'event_type' => HistoryEventType::VersionMarkerRecorded->value,
+            'payload' => [
+                'sequence' => 1,
+                'change_id' => 'patch-1',
+                'version' => WorkflowStub::DEFAULT_VERSION,
+                'min_supported' => WorkflowStub::DEFAULT_VERSION,
+                'max_supported' => 1,
+            ],
+            'recorded_at' => now(),
+        ]);
+
+        $run->forceFill([
+            'last_history_sequence' => 3,
+        ])->save();
+
+        $this->drainReadyTasks();
+
+        $this->assertTrue($workflow->refresh()->completed());
+        $this->assertSame([
+            'patched' => false,
+            'branch' => 'legacy',
+        ], $workflow->output());
+    }
+
+    public function testDeprecatePatchRecordsMarkerAndReturnsNull(): void
+    {
+        Queue::fake();
+
+        $workflow = WorkflowStub::make(TestDeprecatedPatchWorkflow::class, 'patch-deprecated');
+        $workflow->start();
+
+        $this->drainReadyTasks();
+
+        $this->assertTrue($workflow->refresh()->completed());
+        $this->assertSame([
+            'marker_result' => null,
+            'branch' => 'patched',
+        ], $workflow->output());
+
+        /** @var WorkflowHistoryEvent $marker */
+        $marker = WorkflowHistoryEvent::query()
+            ->where('workflow_run_id', $workflow->runId())
+            ->where('event_type', HistoryEventType::VersionMarkerRecorded->value)
+            ->firstOrFail();
+
+        $this->assertSame('patch-1', $marker->payload['change_id'] ?? null);
+        $this->assertSame(1, $marker->payload['version'] ?? null);
+    }
+
     public function testVersionMarkersFailRunWhenRecordedVersionIsNotSupported(): void
     {
         Queue::fake();
diff --git a/tests/Fixtures/V2/TestDeprecatedPatchWorkflow.php b/tests/Fixtures/V2/TestDeprecatedPatchWorkflow.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\V2;
+
+use Workflow\V2\Attributes\Type;
+use function Workflow\V2\deprecatePatch;
+use Workflow\V2\Workflow;
+
+#[Type('test-deprecated-patch-workflow')]
+final class TestDeprecatedPatchWorkflow extends Workflow
+{
+    public function handle(): array
+    {
+        $result = deprecatePatch('patch-1');
+
+        return [
+            'marker_result' => $result,
+            'branch' => 'patched',
+        ];
+    }
+}
diff --git a/tests/Fixtures/V2/TestPatchedWorkflow.php b/tests/Fixtures/V2/TestPatchedWorkflow.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\V2;
+
+use Workflow\V2\Attributes\Type;
+use function Workflow\V2\patched;
+use Workflow\V2\Workflow;
+
+#[Type('test-patched-workflow')]
+final class TestPatchedWorkflow extends Workflow
+{
+    public function handle(): array
+    {
+        $patched = patched('patch-1');
+
+        return [
+            'patched' => $patched,
+            'branch' => $patched ? 'patched' : 'legacy',
+        ];
+    }
+}
diff --git a/tests/Unit/V2/WorkflowFacadeTest.php b/tests/Unit/V2/WorkflowFacadeTest.php
@@ -19,6 +19,7 @@
 use Workflow\V2\Support\UpsertSearchAttributesCall;
 use Workflow\V2\Support\VersionCall;
 use Workflow\V2\Workflow;
+use Workflow\V2\WorkflowStub;
 
 /**
  * The static facade on Workflow\V2\Workflow is a thin delegate to the
@@ -122,6 +123,27 @@ public function testGetVersionReturnsAVersionCall(): void
         $this->assertInstanceOf(VersionCall::class, $call);
     }
 
+    public function testPatchedReturnsAVersionCallWithBooleanResultKind(): void
+    {
+        $call = Workflow::patched('change-one');
+
+        $this->assertInstanceOf(VersionCall::class, $call);
+        $this->assertSame('change-one', $call->changeId);
+        $this->assertSame(WorkflowStub::DEFAULT_VERSION, $call->minSupported);
+        $this->assertSame(1, $call->maxSupported);
+        $this->assertTrue($call->resolveValue(1));
+        $this->assertFalse($call->resolveValue(WorkflowStub::DEFAULT_VERSION));
+    }
+
+    public function testDeprecatePatchReturnsAVersionCallWithNullResultKind(): void
+    {
+        $call = Workflow::deprecatePatch('change-one');
+
+        $this->assertInstanceOf(VersionCall::class, $call);
+        $this->assertSame('change-one', $call->changeId);
+        $this->assertNull($call->resolveValue(1));
+    }
+
     public function testAllReturnsAnAllCall(): void
     {
         $call = Workflow::all([
@@ -183,6 +205,8 @@ public function testEveryFacadeMethodIsStatic(): void
             'sideEffect',
             'continueAsNew',
             'getVersion',
+            'patched',
+            'deprecatePatch',
             'upsertMemo',
             'upsertSearchAttributes',
             'seconds',
