Merge pull request #768 from durable-workflow/fix/744-recorded-version-bounds-stable

Backport recorded version marker validation to stable

Author: rmcdaniel

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2.5.13 - 2026-10-13
+
+- Reject version markers with missing or non-integer canonical bounds,
+  inverted recorded ranges or a recorded version outside those bounds.
+  Validate retained duplicates before replay can skip them.
+- Preserve one numeric decision per change ID across version, patch and
+  deprecation helpers. Valid historical duplicates retain their physical
+  positions and clocks, including when their recorded ranges differ.
+- This compatible backport starts from 2.5.12 and does not include later
+  main/Nexus changes. Marker and command wire shapes are unchanged.
+
 ## 2.5.12 - 2026-10-11
 
 - Enforce a Nexus service call's original deadline during admission, background

composer.json

@@ -79,7 +79,7 @@
             "dev-main": "2.0.x-dev"
         },
         "durable-workflow": {
-            "product-train": "2.5.12",
+            "product-train": "2.5.13",
             "laravel-embedded-upgrade-contract": "resources/laravel-embedded-upgrade-contract.json",
             "laravel-dependency-security-policy": "resources/laravel-dependency-security-policy.json"
         },

docs/api-stability.md

@@ -633,6 +633,15 @@ site before the patch marker existed.
 
 **Evolution rules:**
 
+The numeric version is frozen once per change ID across all three helpers.
+Each invocation validates its own supported range and returns its integer,
+boolean or void projection. Consistent historical duplicate markers keep
+their physical positions and recorded clocks. Their bounds may differ from
+each other and from current code, provided each recorded range contains the
+same frozen version. Canonical markers require both integer bounds;
+inverted ranges, versions outside those bounds and malformed fields are
+invalid history rather than supported version decisions.
+
 An existing recorded version, or the legacy default for a pre-marker run,
 outside the current authored supported range is a replay compatibility fault.
 The embedded engine blocks the affected workflow task with

scripts/ci/test-regression-corpus-policy.py

@@ -1532,6 +1532,38 @@ def test_expected_malformed_service_response_failure_grows_replay_corpus(self) -
         self.assertEqual(1, counts["new_fixture_evidence"])
         self.assertEqual(1, counts["counterfactual_fixture_paths"])
 
+    def test_invalid_recorded_version_range_is_distinct_replay_evidence(self) -> None:
+        fixture = self.official_history_replay_fixture()
+        fixture["id"] = "invalid-recorded-version-range-requires-change"
+        fixture["history"][1]["event_type"] = "VersionMarkerRecorded"
+        fixture["history"][1]["payload"] = {
+            "sequence": 7,
+            "change_id": "same",
+            "version": 1,
+            "min_supported": 2,
+            "max_supported": 5,
+        }
+        del fixture["expected"]
+        fixture["expected_failure"] = {
+            "type": "version_marker_history_range_invalid",
+            "exception": "LogicException",
+        }
+        self.write_json(
+            "tests/Fixtures/V2/ReplayRegression/invalid-recorded-version-range.json",
+            fixture,
+        )
+        (self.root / "src/V2/Support/WorkflowFiberRunner.php").write_text(
+            "<?php\nreturn 'changed';\n",
+            encoding="utf-8",
+        )
+
+        result = self.validate()
+
+        self.assertEqual(0, result.returncode, result.stderr)
+        counts = json.loads(result.stdout)["counts"]["replay"]
+        self.assertEqual(1, counts["new_fixture_evidence"])
+        self.assertEqual(1, counts["counterfactual_fixture_paths"])
+
     def test_malformed_payload_envelopes_are_rejected(self) -> None:
         base = self.official_history_replay_fixture()
         self.write_json(

scripts/ci/validate-regression-corpus.py

@@ -31,6 +31,7 @@
 SEARCH_ATTRIBUTE_TYPE_IDENTITY_MISMATCH = "search_attribute_type_identity_mismatch"
 WORKFLOW_HISTORY_SHAPE_MISMATCH = "workflow_history_shape_mismatch"
 VERSION_MARKER_INCOMPATIBLE_RANGE = "version_marker_incompatible_range"
+VERSION_MARKER_HISTORY_RANGE_INVALID = "version_marker_history_range_invalid"
 UNSUPPORTED_PAYLOAD_CODEC = "unsupported_payload_codec"
 PHP_GOLDEN_REPLAY_WORKFLOW = "Tests\\Fixtures\\V2\\TestGoldenReplayWorkflow"
 PHP_REPLAY_CONSUMERS = {
@@ -1278,6 +1279,7 @@ def _replay_expected_failure(value: Any, context: str) -> Mapping[str, str]:
         SEARCH_ATTRIBUTE_TYPE_IDENTITY_MISMATCH,
         WORKFLOW_HISTORY_SHAPE_MISMATCH,
         VERSION_MARKER_INCOMPATIBLE_RANGE,
+        VERSION_MARKER_HISTORY_RANGE_INVALID,
         UNSUPPORTED_PAYLOAD_CODEC,
     }:
         raise CorpusError(f"{context}.type is unsupported")

src/V2/Support/VersionDecisions.php

@@ -51,6 +51,7 @@ public function replaceMarkers(WorkflowRun|array $history): void
             if (! is_string($changeId) || $changeId === '' || ! is_int($version)) {
                 throw new LogicException('Workflow version markers require a change ID and integer version.');
             }
+            VersionResolver::assertRecordedRange($event, $sequence);
             $original = $this->decisions[$changeId]['version'] ?? $versions[$changeId] ?? $version;
             if ($version !== $original) {
                 throw new LogicException(sprintf(

src/V2/Support/VersionResolver.php

@@ -12,6 +12,29 @@
 
 final class VersionResolver
 {
+    public static function assertRecordedRange(WorkflowHistoryEvent $event, int $sequence): void
+    {
+        $version = $event->payload['version'] ?? null;
+        $minSupported = $event->payload['min_supported'] ?? null;
+        $maxSupported = $event->payload['max_supported'] ?? null;
+        if (! is_int($version) || ! is_int($minSupported) || ! is_int($maxSupported)) {
+            throw new LogicException(sprintf(
+                'Workflow version marker at workflow sequence [%d] requires integer version, min_supported and max_supported.',
+                $sequence,
+            ));
+        }
+
+        if ($minSupported > $maxSupported || $version < $minSupported || $version > $maxSupported) {
+            throw new LogicException(sprintf(
+                'Workflow version marker at workflow sequence [%d] has invalid recorded range [%d, %d] for version [%d].',
+                $sequence,
+                $minSupported,
+                $maxSupported,
+                $version,
+            ));
+        }
+    }
+
     public static function reuse(
         int $version,
         VersionCall $versionCall,
@@ -75,6 +98,7 @@ private static function recordedVersion(
             ));
         }
 
+        self::assertRecordedRange($event, $sequence);
         self::assertSupported($version, $versionCall, $sequence);
 
         return $version;

tests/Fixtures/V2/ReplayRegression/version-marker-invalid-recorded-duplicate-range.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json",
+  "fixture_schema": "durable-workflow.replay-regression/v1",
+  "id": "version-marker-invalid-recorded-duplicate-range",
+  "protocol_version": "1.19",
+  "bindings": ["php"],
+  "consumers": ["workflow-fiber-runner", "query-state-replayer", "workflow-executor"],
+  "workflow": {"type": "Tests\\Fixtures\\V2\\TestSinglePatchReplayWorkflow", "arguments": [], "payload_codec": "avro"},
+  "history": [
+    {"sequence": 1, "event_type": "WorkflowStarted", "payload": {}, "recorded_at": "2026-10-13T01:00:00+00:00"},
+    {"sequence": 2, "event_type": "VersionMarkerRecorded", "payload": {"sequence": 1, "change_id": "same", "version": 1, "min_supported": -1, "max_supported": 1}, "recorded_at": "2026-10-13T01:00:01+00:00"},
+    {"sequence": 3, "event_type": "VersionMarkerRecorded", "payload": {"sequence": 2, "change_id": "same", "version": 1, "min_supported": 2, "max_supported": 5}, "recorded_at": "2026-10-13T01:00:02+00:00"}
+  ],
+  "expected_failure": {"type": "version_marker_history_range_invalid", "exception": "LogicException"}
+}

tests/Unit/V2/LegacyVersionOfflineReplayTest.php

@@ -109,6 +109,8 @@ public function testFallbackDoesNotHideMalformedMarkersOrStepDrift(string $case)
                 'sequence' => 1,
                 'change_id' => 'legacy-upgrade',
                 'version' => 1,
+                'min_supported' => -1,
+                'max_supported' => 2,
             ];
             if ($case === 'missing-change-id') {
                 unset($payload['change_id']);

tests/Unit/V2/VersionDecisionsTest.php

@@ -86,6 +86,8 @@ private function marker(int $sequence, int $version): WorkflowHistoryEvent
                 'sequence' => $sequence,
                 'change_id' => 'same',
                 'version' => $version,
+                'min_supported' => -1,
+                'max_supported' => 2,
             ],
         ]);
     }