Pin in-flight workflow runs to recorded definition fingerprint (#428)

durable-workflow-ops · claude · durable-workflow-ops · commit b7deccbd73e7 · 2026-04-19T18:12:06.000Z
Closes #428.

v2 records `workflow_definition_fingerprint` in every `WorkflowStarted`
event but the engine never reads it when picking the class to execute —
`TypeRegistry::resolveWorkflowClass()` always resolves from the live
`workflow_runs.workflow_class` column. When a deploy promotes a new
class under the same `workflow_type` while a run is parked on a signal/
timer, the replayed run silently starts executing the new class's code
path against the existing history.

Adds a reverse-lookup registry on `WorkflowDefinition` and a
fingerprint-aware resolver on `WorkflowDefinitionFingerprint`:

- `WorkflowDefinition::fingerprint()` now also populates
  `$classesByFingerprint` so any class whose fingerprint has been
  computed is resolvable by its recorded hash.
- `WorkflowDefinition::findClassByFingerprint()` is the explicit reverse
  lookup; null when no such class is known in the current process.
- `WorkflowDefinitionFingerprint::resolveClassForRun()` prefers the
  class whose source fingerprint matches the run's `WorkflowStarted`
  payload. It falls back to `TypeRegistry::resolveWorkflowClass()` for
  legacy runs (no fingerprint), the fast-path match (recorded equals
  current), and for post-deploy runs whose old class is no longer
  loadable — `RunDetailView` surfaces the fingerprint drift either way.

Wired into the two behavior-pinning call sites:
  - `WorkflowExecutor::run()` (task execution)
  - `QueryStateReplayer::replayState()` (query/memo replay)

Controlled by `workflows.v2.compatibility.pin_to_recorded_fingerprint`
(env `WORKFLOW_V2_PIN_TO_RECORDED_FINGERPRINT`), default `true`. Deploys
that intentionally hot-swap definitions can opt out by setting it to
false to restore the pre-#428 behavior.

Also tightens the `VersionCall` dispatcher so `ensureStepHistoryCompatible`
runs only on paths that actually advance the workflow sequence. The
legacy-default path records no marker and does not advance, so the
next yielded step (activity, timer, child, …) legitimately occupies
the same sequence slot. Under the old ordering, a legacy run that
yielded `getVersion` followed by `activity()` would record activity
events at the same sequence and fail the subsequent replay with
`HistoryEventShapeMismatchException` at the version-marker step.

Unskips both V2VersionWorkflowTest tests tracked in #428:
  - testSameCompatibilityUsesRecordedDefinitionFingerprint…
  - testOlderCompatibilityFallsBackToDefaultVersionWithoutRecordingMarker…

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/V2/Support/QueryStateReplayer.php b/src/V2/Support/QueryStateReplayer.php
@@ -52,7 +52,7 @@ public function replayState(WorkflowRun $run): ReplayState
             'childLinks.childRun.historyEvents',
         ]);
 
-        $workflowClass = TypeRegistry::resolveWorkflowClass($run->workflow_class, $run->workflow_type);
+        $workflowClass = WorkflowDefinitionFingerprint::resolveClassForRun($run);
         $workflow = new $workflowClass($run);
         $this->syncWorkflowCursor($workflow, 1);
         $entryMethod = EntryMethod::forWorkflow($workflow);
diff --git a/src/V2/Support/WorkflowDefinition.php b/src/V2/Support/WorkflowDefinition.php
@@ -19,6 +19,24 @@ final class WorkflowDefinition
      */
     private static array $fingerprints = [];
 
+    /**
+     * Reverse index of {@see $fingerprints}: fingerprint hash → class-string.
+     *
+     * Populated lazily by {@see fingerprint()} so any workflow class whose
+     * fingerprint has been computed is resolvable by its recorded hash.
+     * Used by {@see WorkflowDefinitionFingerprint::resolveClassForRun()} to
+     * pin in-flight runs to the definition snapshot captured in their
+     * WorkflowStarted history event, even after `workflow_runs.workflow_class`
+     * has been updated to point at a newer class for the same workflow_type.
+     *
+     * When two registered classes compute the same fingerprint (they would
+     * produce identical replay behavior by definition), the first-registered
+     * class wins — subsequent identical-fingerprint registrations are ignored.
+     *
+     * @var array<string, class-string>
+     */
+    private static array $classesByFingerprint = [];
+
     /**
      * @var array<class-string, list<string>>
      */
@@ -304,14 +322,40 @@ public static function fingerprint(string $class): ?string
             self::collectFingerprintSources(new ReflectionClass($class), $sources, $seen);
             ksort($sources);
 
-            self::$fingerprints[$class] = $sources === []
+            $fingerprint = $sources === []
                 ? null
                 : 'sha256:' . hash('sha256', json_encode($sources, JSON_THROW_ON_ERROR));
+
+            self::$fingerprints[$class] = $fingerprint;
+
+            if ($fingerprint !== null && ! array_key_exists($fingerprint, self::$classesByFingerprint)) {
+                self::$classesByFingerprint[$fingerprint] = $class;
+            }
         }
 
         return self::$fingerprints[$class];
     }
 
+    /**
+     * Reverse lookup: return the workflow class whose source fingerprint
+     * matches `$fingerprint`, or null if no such class has been seen in the
+     * current process.
+     *
+     * The reverse index is populated lazily by {@see fingerprint()}, so this
+     * resolver only sees classes whose fingerprint has already been computed.
+     * Callers that want to pin an in-flight run to the class that produced its
+     * `WorkflowStarted` fingerprint should warm the index by calling
+     * `fingerprint()` for every candidate class at boot — the current run's
+     * `workflow_class` plus every configured class under
+     * `workflows.v2.types.workflows` is a good seed.
+     *
+     * @return class-string|null
+     */
+    public static function findClassByFingerprint(string $fingerprint): ?string
+    {
+        return self::$classesByFingerprint[$fingerprint] ?? null;
+    }
+
     /**
      * @param class-string $class
      * @return list<string>
diff --git a/src/V2/Support/WorkflowDefinitionFingerprint.php b/src/V2/Support/WorkflowDefinitionFingerprint.php
@@ -8,6 +8,7 @@
 use Workflow\V2\Enums\HistoryEventType;
 use Workflow\V2\Models\WorkflowHistoryEvent;
 use Workflow\V2\Models\WorkflowRun;
+use Workflow\V2\Workflow;
 
 final class WorkflowDefinitionFingerprint
 {
@@ -41,6 +42,78 @@ public static function matchesCurrent(WorkflowRun $run): ?bool
         return hash_equals($recorded, $current);
     }
 
+    /**
+     * Resolve the workflow class to use for a given in-flight run, preferring
+     * the class that matches the `workflow_definition_fingerprint` recorded
+     * in the run's `WorkflowStarted` history event.
+     *
+     * This keeps a run pinned to the definition it started under when a
+     * deploy has promoted a new class under the same `workflow_type` while
+     * the run is parked on a signal/timer. Without pinning the engine picks
+     * the new class from `workflow_runs.workflow_class` and runs the wrong
+     * code path against the existing history.
+     *
+     * Resolution order:
+     *  1. Fast path — if no fingerprint was recorded (legacy run), or the
+     *     recorded fingerprint equals the current class's fingerprint, or
+     *     pinning is disabled via config, fall back to
+     *     {@see TypeRegistry::resolveWorkflowClass()}.
+     *  2. Reverse-lookup — ask the definition registry for the class whose
+     *     source fingerprint matches the recorded hash. Requires the class
+     *     to have been seen by {@see WorkflowDefinition::fingerprint()} in
+     *     the current process.
+     *  3. Fall back — if the registry has no match for the recorded
+     *     fingerprint, resolve via {@see TypeRegistry::resolveWorkflowClass()}
+     *     so the run still makes progress rather than failing hard. The
+     *     `RunDetailView` fingerprint-drift signal still surfaces the
+     *     mismatch to operators.
+     *
+     * Controlled by `workflows.v2.compatibility.pin_to_recorded_fingerprint`
+     * (default `true`). Set to `false` to restore hot-swap behavior.
+     *
+     * @return class-string<Workflow>
+     */
+    public static function resolveClassForRun(WorkflowRun $run): string
+    {
+        $fallbackClass = TypeRegistry::resolveWorkflowClass($run->workflow_class, $run->workflow_type);
+
+        if (! self::pinningEnabled()) {
+            return $fallbackClass;
+        }
+
+        $recorded = self::recordedForRun($run);
+
+        if ($recorded === null) {
+            return $fallbackClass;
+        }
+
+        // Warm the reverse index for the fallback class so repeated calls
+        // for a run whose fingerprint matches the current class stay on the
+        // fast path (O(1) hash-equals) instead of running a registry lookup.
+        $currentFingerprint = WorkflowDefinition::fingerprint($fallbackClass);
+
+        if ($currentFingerprint !== null && hash_equals($recorded, $currentFingerprint)) {
+            return $fallbackClass;
+        }
+
+        $pinnedClass = WorkflowDefinition::findClassByFingerprint($recorded);
+
+        if ($pinnedClass !== null && is_subclass_of($pinnedClass, Workflow::class)) {
+            return $pinnedClass;
+        }
+
+        return $fallbackClass;
+    }
+
+    private static function pinningEnabled(): bool
+    {
+        $configured = function_exists('config')
+            ? config('workflows.v2.compatibility.pin_to_recorded_fingerprint', true)
+            : true;
+
+        return (bool) $configured;
+    }
+
     private static function workflowStartedEvent(WorkflowRun $run): ?WorkflowHistoryEvent
     {
         if ($run->relationLoaded('historyEvents')) {
diff --git a/src/V2/Support/WorkflowExecutor.php b/src/V2/Support/WorkflowExecutor.php
@@ -73,7 +73,7 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
             return null;
         }
 
-        $workflowClass = TypeRegistry::resolveWorkflowClass($run->workflow_class, $run->workflow_type);
+        $workflowClass = WorkflowDefinitionFingerprint::resolveClassForRun($run);
         $workflow = new $workflowClass($run);
         $entryMethod = EntryMethod::forWorkflow($workflow);
         $arguments = $workflow->resolveMethodDependencies($run->workflowArguments(), $entryMethod);
@@ -451,16 +451,33 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
                     return $this->restartAfterPendingUpdateFailure($run, $task);
                 }
 
-                if (! $this->ensureStepHistoryCompatible($run, $task, $sequence, WorkflowStepHistory::VERSION_MARKER)) {
-                    return null;
-                }
-
                 $versionMarkerEvent = $this->versionMarkerEvent($run, $sequence);
 
                 try {
                     $resolution = VersionResolver::resolve($run, $versionMarkerEvent, $current, $sequence);
-                    $version = $resolution->version;
+                } catch (Throwable $throwable) {
+                    $this->failRun($run, $task, $throwable, 'workflow_run', $run->id);
+
+                    return null;
+                }
 
+                // Only assert VERSION_MARKER history shape on paths that will
+                // occupy a history slot at this sequence (recorded / fresh).
+                // The legacy-default path records nothing and does not advance
+                // the workflow sequence — the next yield (activity, timer…)
+                // legitimately shares this slot, so checking for
+                // VERSION_MARKER-compatibility here would spuriously reject
+                // legacy replays that have since produced ACTIVITY/TIMER
+                // events at the same sequence.
+                if ($resolution->advancesSequence
+                    && ! $this->ensureStepHistoryCompatible($run, $task, $sequence, WorkflowStepHistory::VERSION_MARKER)
+                ) {
+                    return null;
+                }
+
+                $version = $resolution->version;
+
+                try {
                     if ($resolution->shouldRecordMarker) {
                         $versionMarkerEvent = $this->recordVersionMarker($run, $task, $sequence, $current, $version);
                     }
diff --git a/src/config/workflows.php b/src/config/workflows.php
@@ -69,6 +69,18 @@
             'supported' => env('WORKFLOW_V2_SUPPORTED_COMPATIBILITIES', null),
             'namespace' => env('WORKFLOW_V2_COMPATIBILITY_NAMESPACE', null),
             'heartbeat_ttl_seconds' => (int) env('WORKFLOW_V2_COMPATIBILITY_HEARTBEAT_TTL', 30),
+            // When true (the default), in-flight runs resolve their workflow
+            // class from the `workflow_definition_fingerprint` recorded in
+            // their WorkflowStarted history event instead of the live
+            // `workflow_runs.workflow_class` column. This keeps a run pinned
+            // to the definition snapshot it started under even after a deploy
+            // swaps the class pointer for the same workflow_type.
+            //
+            // Set to false only if your deploy intentionally hot-swaps
+            // workflow classes mid-run and wants the replacement class to
+            // execute against the existing history from the next task
+            // forward.
+            'pin_to_recorded_fingerprint' => (bool) env('WORKFLOW_V2_PIN_TO_RECORDED_FINGERPRINT', true),
         ],
         'history_budget' => [
             'continue_as_new_event_threshold' => (int) env('WORKFLOW_V2_CONTINUE_AS_NEW_EVENT_THRESHOLD', 10000),
diff --git a/tests/Feature/V2/V2VersionWorkflowTest.php b/tests/Feature/V2/V2VersionWorkflowTest.php
@@ -266,8 +266,6 @@ public function testVersionMarkersRecordAfterEarlierSignalsOnCurrentCompatibilit
 
     public function testSameCompatibilityUsesRecordedDefinitionFingerprintToKeepOlderRunOnDefaultVersion(): void
     {
-        $this->markTestSkipped('Fingerprint-pinned workflow class resolution is not yet implemented; tracked in #428.');
-
         config()
             ->set('workflows.v2.compatibility.current', 'build-b');
         config()
@@ -331,8 +329,6 @@ public function testSameCompatibilityUsesRecordedDefinitionFingerprintToKeepOlde
 
     public function testOlderCompatibilityFallsBackToDefaultVersionWithoutRecordingMarkerAfterEarlierSignal(): void
     {
-        $this->markTestSkipped('Fingerprint-pinned workflow class resolution is not yet implemented; tracked in #428.');
-
         config()
             ->set('workflows.v2.compatibility.current', 'build-b');
         config()
