Skip to content

Commit 97119f3

Browse files
authored
Fix stable persisted workflow-start clocks (#148)
* Seed replay clocks from persisted workflow start time * Release stable persisted-clock correction as 2.5.13 --------- Co-authored-by: Durable Workflow <support@durable-workflow.com>
1 parent db0c029 commit 97119f3

6 files changed

Lines changed: 142 additions & 9 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
66

77
## [Unreleased]
88

9+
## [2.5.13] - 2026-10-13
10+
11+
### Fixed
12+
- Seed deterministic workflow-start time from recorded history when the explicit
13+
payload timestamp is absent. Cold `now()` and UUIDv7 reads use persisted time;
14+
missing or invalid replay time produces an explicit diagnostic.
15+
916
## [2.5.12] - 2026-10-13
1017

1118
### Fixed

‎pyproject.toml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "durable-workflow"
7-
version = "2.5.12"
7+
version = "2.5.13"
88
description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
99
readme = "README.md"
1010
requires-python = ">=3.10"
@@ -71,8 +71,8 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
7171
durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"
7272

7373
[tool.durable-workflow]
74-
product-train = "2.5.12"
75-
registry-version = "2.5.12"
74+
product-train = "2.5.13"
75+
registry-version = "2.5.13"
7676
supported-server-versions = "2.5.16"
7777
worker-protocol-version = "1.20"
7878
control-plane-version = "2"

‎src/durable_workflow/workflow.py‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1937,10 +1937,14 @@ def __init__(
19371937
workflow_command_id: str | None = None,
19381938
cancel_requested: bool = False,
19391939
allow_cancellation_scope_authoring: bool = False,
1940+
_allow_wall_clock: bool = True,
19401941
) -> None:
19411942
self._workflow_id = workflow_id
19421943
self._run_id = run_id
1943-
self._current_time = current_time or datetime.now(timezone.utc)
1944+
self._current_time = current_time
1945+
if self._current_time is None and _allow_wall_clock:
1946+
self._current_time = datetime.now(timezone.utc)
1947+
self._replay_clock_error: str | None = None
19441948
self._workflow_command_id = workflow_command_id or run_id or workflow_id
19451949
self._cancel_requested = bool(cancel_requested)
19461950
self._cancellation_request_id: str | None = None
@@ -2538,6 +2542,12 @@ def continue_as_new(
25382542
return ContinueAsNew(workflow_type=workflow_type, arguments=list(args), task_queue=task_queue)
25392543

25402544
def now(self) -> datetime:
2545+
"""Return the persisted workflow-start time, fixed during replay."""
2546+
if self._current_time is None:
2547+
raise NonDeterministicReplayError(
2548+
0, "persisted workflow-start clock", [],
2549+
detail=self._replay_clock_error or "Workflow replay clock unavailable: missing persisted start time",
2550+
)
25412551
return self._current_time
25422552

25432553
def random(self) -> random.Random:
@@ -2548,7 +2558,7 @@ def uuid4(self) -> uuid.UUID:
25482558
return uuid.UUID(bytes=rand_bytes, version=4)
25492559

25502560
def uuid7(self) -> uuid.UUID:
2551-
timestamp_ms = int(self._current_time.timestamp() * 1000)
2561+
timestamp_ms = int(self.now().timestamp() * 1000)
25522562
if timestamp_ms < 0 or timestamp_ms >= (1 << 48):
25532563
raise ValueError("ctx.uuid7() requires ctx.now() within the UUIDv7 timestamp range")
25542564

@@ -4276,13 +4286,22 @@ def _replay_state(
42764286
resolved_sequences.add(sequence)
42774287

42784288
workflow_start_time: datetime | None = None
4289+
replay_clock_error = "Workflow replay clock unavailable: missing WorkflowStarted persisted start time"
42794290
for ev in events:
42804291
etype = _history_event_type(ev)
42814292
if etype == "WorkflowStarted":
4282-
ts = (ev.get("payload") or {}).get("timestamp")
4283-
if ts:
4284-
with contextlib.suppress(ValueError, TypeError):
4285-
workflow_start_time = datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
4293+
start_payload = ev.get("payload")
4294+
if not isinstance(start_payload, Mapping):
4295+
start_payload = {}
4296+
explicit_time = "timestamp" in start_payload
4297+
ts = start_payload.get("timestamp") if explicit_time else ev.get("recorded_at")
4298+
clock_source = "payload.timestamp" if explicit_time else "recorded_at"
4299+
replay_clock_error = f"Workflow replay clock unavailable: invalid or missing WorkflowStarted.{clock_source}"
4300+
if isinstance(ts, str):
4301+
with contextlib.suppress(ValueError):
4302+
parsed_time = datetime.fromisoformat(ts.replace("Z", "+00:00"))
4303+
if parsed_time.tzinfo is not None and parsed_time.utcoffset() is not None:
4304+
workflow_start_time = parsed_time
42864305
break
42874306

42884307
for sequence, membership in scope_history.memberships.items():
@@ -4298,7 +4317,9 @@ def _replay_state(
42984317
workflow_command_id=workflow_command_id,
42994318
cancel_requested=cancel_requested,
43004319
allow_cancellation_scope_authoring=allow_cancellation_scope_authoring,
4320+
_allow_wall_clock=not events,
43014321
)
4322+
ctx._replay_clock_error = replay_clock_error if workflow_start_time is None else None
43024323
# Continue-as-new cursor checkpoints describe instance state that predates
43034324
# this run. Seed them before the workflow opens its first stream wait so
43044325
# both the durable wait key and worker acknowledgement use the global
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/durable-workflow/.github/main/regression-corpus/evidence-schema.json",
3+
"fixture_schema": "durable-workflow.replay-regression/v1",
4+
"id": "workflow-start-recorded-clock",
5+
"protocol_version": "1.20",
6+
"bindings": ["python"],
7+
"workflow": {"type": "tests.replay.persisted-clock", "input": [], "payload_codec": "avro"},
8+
"history": [{"event_type": "WorkflowStarted", "recorded_at": "2026-06-01T12:00:00.123456Z", "payload": {}}],
9+
"expected": {"type": "complete_workflow", "result": "2026-06-01T12:00:00.123456+00:00"}
10+
}

‎tests/test_replay_clock.py‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
from __future__ import annotations
2+
3+
from copy import deepcopy
4+
from datetime import datetime
5+
from typing import Any
6+
from uuid import UUID
7+
8+
import pytest
9+
10+
from durable_workflow import workflow
11+
from durable_workflow.errors import NonDeterministicReplayError
12+
from durable_workflow.workflow import CompleteWorkflow, WorkflowContext, replay
13+
14+
15+
@workflow.defn(name="tests.replay.persisted-clock")
16+
class PersistedClockWorkflow:
17+
def run(self, ctx: WorkflowContext) -> str:
18+
return ctx.now().isoformat(timespec="microseconds")
19+
20+
21+
@workflow.defn(name="tests.replay.persisted-uuid7")
22+
class PersistedUUID7Workflow:
23+
def run(self, ctx: WorkflowContext) -> str:
24+
return str(ctx.uuid7())
25+
26+
27+
@workflow.defn(name="tests.replay.marker-clock")
28+
class MarkerClockWorkflow:
29+
def run(self, ctx: WorkflowContext): # type: ignore[no-untyped-def]
30+
before = ctx.now().isoformat(timespec="microseconds")
31+
version = yield ctx.get_version("clock-case", 0, 7)
32+
after = ctx.now().isoformat(timespec="microseconds")
33+
return [before, version, after, str(ctx.uuid7())]
34+
35+
36+
def result(workflow_cls: type, history: list[dict[str, Any]]) -> Any:
37+
outcome = replay(workflow_cls, history, [], run_id="original-clock-run", payload_codec="avro")
38+
assert len(outcome.commands) == 1
39+
command = outcome.commands[0]
40+
assert isinstance(command, CompleteWorkflow)
41+
return command.result
42+
43+
44+
def test_recorded_start_time_survives_repeated_cold_reads_and_later_marker() -> None:
45+
history = [
46+
{"event_type": "WorkflowStarted", "recorded_at": "2026-06-01T12:00:00.123456Z", "payload": {}},
47+
{"event_type": "VersionMarkerRecorded", "recorded_at": "2026-06-01T12:00:03.987654Z",
48+
"payload": {"sequence": 1, "change_id": "clock-case", "version": 7,
49+
"min_supported": 0, "max_supported": 7}},
50+
]
51+
original = deepcopy(history)
52+
first = result(MarkerClockWorkflow, history)
53+
second = result(MarkerClockWorkflow, history)
54+
assert first == second
55+
assert first[:3] == ["2026-06-01T12:00:00.123456+00:00", 7, "2026-06-01T12:00:00.123456+00:00"]
56+
assert UUID(first[3]).int >> 80 == int(datetime.fromisoformat(first[0]).timestamp() * 1000)
57+
assert history == original
58+
59+
60+
def test_explicit_payload_time_retains_precedence() -> None:
61+
history = [{"event_type": "WorkflowStarted", "recorded_at": "2026-06-01T12:00:00.123456Z",
62+
"payload": {"timestamp": "2026-06-01T14:01:02.654321+02:00"}}]
63+
assert result(PersistedClockWorkflow, history) == "2026-06-01T14:01:02.654321+02:00"
64+
65+
66+
@pytest.mark.parametrize("invalid", [None, False, 123, "", "not-a-time", "2026-06-01T12:00:00"])
67+
@pytest.mark.parametrize("explicit", [False, True])
68+
@pytest.mark.parametrize("workflow_cls", [PersistedClockWorkflow, PersistedUUID7Workflow])
69+
def test_clock_helpers_refuse_invalid_time_without_fallback(
70+
invalid: Any, explicit: bool, workflow_cls: type,
71+
) -> None:
72+
event: dict[str, Any] = {"event_type": "WorkflowStarted", "payload": {}}
73+
if explicit:
74+
event["recorded_at"] = "2026-06-01T12:00:00.123456Z"
75+
event["payload"]["timestamp"] = invalid
76+
else:
77+
event["recorded_at"] = invalid
78+
with pytest.raises(NonDeterministicReplayError, match="Workflow replay clock unavailable"):
79+
result(workflow_cls, [event])
80+
81+
82+
@pytest.mark.parametrize("history", [
83+
[{"event_type": "WorkflowStarted", "payload": {}}],
84+
[{"event_type": "SignalReceived", "payload": {"signal_name": "unhandled"}}],
85+
])
86+
def test_missing_replay_time_is_explicit(history: list[dict[str, Any]]) -> None:
87+
with pytest.raises(NonDeterministicReplayError, match="Workflow replay clock unavailable"):
88+
result(PersistedClockWorkflow, history)
89+
90+
91+
def test_empty_local_authoring_remains_available() -> None:
92+
assert datetime.fromisoformat(result(PersistedClockWorkflow, [])).tzinfo is not None
93+
assert UUID(result(PersistedUUID7Workflow, [])).version == 7

‎tests/test_replay_regression_corpus.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
RepeatedPatchWorkflow,
3535
)
3636
from tests.test_pending_operation_replay import PendingOperation
37+
from tests.test_replay_clock import PersistedClockWorkflow
3738
from tests.test_update_signal_condition_replay import (
3839
PostConditionReceiversWorkflow,
3940
UpdateSignalConditionTimerWorkflow,
@@ -278,6 +279,7 @@ def run(self, ctx: WorkflowContext): # type: ignore[no-untyped-def]
278279

279280

280281
WORKFLOWS = [
282+
PersistedClockWorkflow,
281283
NexusTargetWorkflow,
282284
UnsupportedAsyncWorkflow,
283285
ChildPolicyAuthorWorkflow,

0 commit comments

Comments
 (0)