workflowd 0.1.0__py3-none-any.whl

workflowd-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: workflowd
+Version: 0.1.0
+Summary: Python SDK for workflowd, a single-binary durable workflow engine. Zero dependencies.
+Author: Joseph Olayanju
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Olayanju-1234/durable-workflow-engine
+Project-URL: Documentation, https://github.com/Olayanju-1234/durable-workflow-engine/tree/main/sdks#readme
+Project-URL: Issues, https://github.com/Olayanju-1234/durable-workflow-engine/issues
+Keywords: workflow,durable-execution,orchestration,saga,temporal
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# workflowd (Python SDK)
+
+Write durable workflows in plain Python and run them on
+[workflowd](https://github.com/Olayanju-1234/durable-workflow-engine), a single-binary
+durable workflow engine. Zero dependencies: the standard library only.
+
+```python
+from workflowd import ActivityFailure, Worker, WorkflowFailure
+
+worker = Worker(address="http://localhost:8233")
+
+@worker.workflow("Order")
+def order(ctx):
+    reserved = ctx.activity("reserve", ctx.input)
+    ctx.sleep("settle", 2.0)  # durable: survives an engine restart
+    try:
+        ctx.activity("charge", reserved)
+    except ActivityFailure as err:
+        ctx.activity("release", reserved)  # compensate
+        raise WorkflowFailure(f"charge failed: {err}")
+    return ctx.activity("ship", reserved)
+
+@worker.activity("reserve")
+def reserve(payload):
+    return f"reserved({payload})"
+
+worker.run()
+```
+
+More of the API:
+
+```python
+# Run activities in parallel; race a signal against a deadline.
+stock, price = ctx.wait_all(ctx.activity_async("stock", sku), ctx.activity_async("price", sku))
+late = ctx.wait_any(ctx.wait_for_signal_async("reply", "approved"), ctx.sleep_async("sla", 3600)) == 1
+
+# Retry a failed attempt before the workflow sees the error; JSON and bytes payloads.
+receipt = ctx.activity("charge", {"amount": 42}, retry=RetryPolicy(max_attempts=3, initial_backoff=0.5), decode="json")
+
+# Change code safely while executions are in flight; record a non-deterministic value once.
+if ctx.get_version("fraud-check", DEFAULT_VERSION, 1) == 1:
+    ctx.activity("fraud-check", receipt)
+order_id = ctx.side_effect("id", lambda: str(uuid.uuid4()))
+```
+
+A cluster: `Worker(addresses=["http://n1:8233", "http://n2:8233", "http://n3:8233"])` follows
+the leader. Activities longer than the lease heartbeat automatically; an activity taking a
+second `info` argument can check `info["lease_lost"]`.
+
+For an engine with auth and TLS: `Worker(address="https://…:8233", token=..., ca_file=...)`
+(`ca_file` only for a private CA).
+
+Workflow code must be deterministic: no clocks, randomness or I/O except through `ctx`.
+How replay works, and the protocol, are in the
+[SDK guide](https://github.com/Olayanju-1234/durable-workflow-engine/tree/main/sdks#readme).
+Pre-alpha: the API may change. Apache-2.0.

workflowd-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+workflowd.py,sha256=xkRfF9ApJNHzC4fDSNAHqWj1c8HbpK-sllrfKLn2Goo,28595
+workflowd-0.1.0.dist-info/licenses/LICENSE,sha256=-piAHD-2x5h-8tycZP4-h9SabuYx7M3z4BdEeL_8v7w,11338
+workflowd-0.1.0.dist-info/licenses/NOTICE,sha256=KQP9lmEsR0AAzjb7wCFXwLRYsZp5OBiXpRmyQO9FJoA,201
+workflowd-0.1.0.dist-info/METADATA,sha256=DMUjAyNJHfS2IqPcY7vCjP_sAokmSf6G1R_h4w3sds4,3128
+workflowd-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+workflowd-0.1.0.dist-info/top_level.txt,sha256=jDNbDXERwBw0Js41iKHAvLp7XWcyRSd2kmjabX3UZCk,10
+workflowd-0.1.0.dist-info/RECORD,,

workflowd-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

workflowd-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Olayanju
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

workflowd-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,6 @@
+durable-workflow-engine
+Copyright 2026 Olayanju
+
+This product includes software developed by the durable-workflow-engine authors.
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file.

workflowd-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+workflowd

workflowd.py

@@ -0,0 +1,706 @@
+"""workflowd — Python SDK.
+
+Write durable workflows in Python. Zero dependencies: this module uses only the
+standard library (urllib, json, threading), so there is no pip install and no
+protobuf toolchain.
+
+The model in one paragraph: your workflow function is re-run from the top every
+time the engine needs a decision. Each durable call (``ctx.activity``,
+``ctx.sleep``, ``ctx.wait_for_signal``, ``ctx.get_version``,
+``ctx.side_effect``) is matched against what already happened. Completed steps
+return their recorded result instantly; the first step with no result yet
+becomes the command sent back to the engine. The function runs many times, but
+each side effect happens exactly once.
+
+Usage::
+
+    from workflowd import Worker, WorkflowFailure, ActivityFailure, RetryPolicy
+
+    worker = Worker(address="http://localhost:8233")
+
+    @worker.workflow("OrderWorkflow")
+    def order_workflow(ctx):
+        order = ctx.input_as("json")
+        reserved = ctx.activity("reserve", order, decode="json")
+        ctx.sleep("settle", 2.0)
+        try:
+            ctx.activity("charge", reserved, retry=RetryPolicy(max_attempts=3, initial_backoff=0.5))
+        except ActivityFailure as err:
+            ctx.activity("release", reserved)      # compensate
+            raise WorkflowFailure(f"charge failed: {err}")
+        return ctx.activity("ship", reserved)
+
+    @worker.activity("reserve", decode="json")
+    def reserve(order):
+        return {"id": order["id"], "held": True}
+
+    worker.run()
+
+Payloads: ``str`` travels as UTF-8 text, ``bytes`` as raw bytes, anything else
+as JSON. Results come back as ``str`` unless you pass ``decode="json"`` or
+``decode="bytes"``.
+
+Clusters: pass every node in ``addresses``. A follower answers 503 naming the
+leader; the worker moves there and registers its workflow types again.
+
+Workflow code must be deterministic: no clocks, no randomness, no I/O except
+through ``ctx``. Anything else will diverge on replay.
+"""
+
+from __future__ import annotations
+
+import base64
+import inspect
+import json
+import random
+import ssl
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+__all__ = [
+    "Worker",
+    "Context",
+    "Future",
+    "RetryPolicy",
+    "WorkflowFailure",
+    "ActivityFailure",
+    "DEFAULT_VERSION",
+    "decide",
+]
+
+SDK_VERSION = "python/0.1.0"
+
+# The version get_version returns to executions that predate the change.
+DEFAULT_VERSION = -1
+
+
+class WorkflowFailure(Exception):
+    """Raise inside a workflow to fail it deliberately."""
+
+
+class ActivityFailure(Exception):
+    """Raised when an activity recorded a failure. Catch it to compensate."""
+
+    def __init__(self, step_name: str, message: str):
+        super().__init__(message)
+        self.step_name = step_name
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Retry a failed activity before the workflow sees its error.
+
+    ``max_attempts`` counts the first attempt (1 means no retries). The wait
+    before each retry starts at ``initial_backoff`` seconds and doubles, capped
+    at ``max_backoff`` (0 means no cap). It is recorded with the step, so the
+    retries survive engine restarts.
+    """
+
+    max_attempts: int = 1
+    initial_backoff: float = 0.0
+    max_backoff: float = 0.0
+
+    def to_wire(self) -> dict:
+        return {
+            "max_attempts": self.max_attempts,
+            "initial_backoff_ms": max(0, int(self.initial_backoff * 1000)),
+            "max_backoff_ms": max(0, int(self.max_backoff * 1000)),
+        }
+
+
+class _Yield(BaseException):
+    """Internal control-flow signal: the code waits on a step with no result yet.
+
+    Deliberately derived from BaseException, not Exception, so a workflow's
+    ``except Exception`` around an activity cannot accidentally swallow it. The
+    commands to send are the ones the context collected before it was raised.
+    """
+
+    def __init__(self):
+        super().__init__("workflowd internal yield")
+
+
+class _NonDeterminism(BaseException):
+    """The workflow code no longer matches the recorded history.
+
+    A BaseException for the same reason as _Yield: workflow code must not be
+    able to catch it and carry on with a corrupt replay.
+    """
+
+
+# ---- payloads ----
+
+
+def _put_payload(obj: dict, field: str, value: Any) -> dict:
+    """Encode value onto obj[field] (text) or obj[field + "_base64"] (bytes)."""
+    if value is None:
+        obj[field] = ""
+    elif isinstance(value, str):
+        obj[field] = value
+    elif isinstance(value, (bytes, bytearray, memoryview)):
+        obj[field + "_base64"] = base64.b64encode(bytes(value)).decode("ascii")
+    else:
+        obj[field] = json.dumps(value)
+    return obj
+
+
+def read_payload(obj: Optional[dict], field: str, decode: str = "text") -> Any:
+    """Read a payload. The engine adds ``<field>_base64`` only when the bytes
+    are not valid UTF-8, so the text field is exact otherwise."""
+    obj = obj or {}
+    b64 = obj.get(field + "_base64")
+    if decode == "bytes":
+        return base64.b64decode(b64) if b64 else (obj.get(field) or "").encode()
+    text = base64.b64decode(b64).decode("utf-8", errors="replace") if b64 else (obj.get(field) or "")
+    if decode == "json":
+        return None if text == "" else json.loads(text)
+    if decode == "text":
+        return text
+    raise ValueError(f"unknown decode {decode!r}; use 'text', 'json' or 'bytes'")
+
+
+class Future:
+    """The result of a durable call started without waiting for it (the
+    ``*_async`` methods). ``result()`` returns it, or blocks the workflow until
+    the step has one."""
+
+    def __init__(self, ctx: "Context", seq: int, name: str, decode: str):
+        self._ctx, self._seq, self._name, self._decode = ctx, seq, name, decode
+
+    def _recorded(self) -> Optional[dict]:
+        rec = self._ctx._steps[self._seq - 1] if self._seq <= len(self._ctx._steps) else None
+        if rec is not None and rec.get("status") in ("COMPLETED", "FAILED"):
+            return rec
+        return None  # not started yet, in flight, or being retried
+
+    def result(self) -> Any:
+        rec = self._recorded()
+        if rec is None:
+            raise _Yield()
+        if rec.get("status") == "FAILED":
+            raise ActivityFailure(self._name, rec.get("error") or "activity failed")
+        return read_payload(rec, "output", self._decode)
+
+
+class Context:
+    """What a workflow function receives. Every method is durable."""
+
+    def __init__(self, task: dict):
+        self.task = task
+        self.input: str = read_payload(task, "input")
+        self.workflow_id: str = task.get("workflow_id", "")
+        self._steps: List[dict] = task.get("steps") or []
+        self._signals: List[dict] = task.get("signals") or []
+        self._next = 0
+        self._versions: Dict[str, int] = {}
+        self._pending: List[dict] = []  # new commands, in sequence order
+
+    def input_as(self, decode: str = "text") -> Any:
+        """The start input decoded as "text" (same as ctx.input), "json" or "bytes"."""
+        return read_payload(self.task, "input", decode)
+
+    def activity(
+        self,
+        name: str,
+        payload: Any = "",
+        *,
+        retry: Optional[RetryPolicy] = None,
+        decode: str = "text",
+    ) -> Any:
+        """Run a named activity on a worker and return its output."""
+        return self.activity_async(name, payload, retry=retry, decode=decode).result()
+
+    def activity_async(
+        self,
+        name: str,
+        payload: Any = "",
+        *,
+        retry: Optional[RetryPolicy] = None,
+        decode: str = "text",
+    ) -> Future:
+        """Start an activity and return at once, so several run in parallel::
+
+            charge = ctx.activity_async("charge", order)
+            email = ctx.activity_async("email", order)
+            ctx.wait_all(charge, email)
+        """
+        command = _put_payload({"type": "schedule_activity", "step_name": name}, "input", payload)
+        if retry is not None:
+            command["retry_policy"] = retry.to_wire()
+        return self._issue("ACTIVITY", name, command, decode)
+
+    def sleep(self, name: str, seconds: float) -> str:
+        """Pause durably. Survives engine restarts."""
+        return self.sleep_async(name, seconds).result()
+
+    def sleep_async(self, name: str, seconds: float) -> Future:
+        """Start a durable timer and return at once; result() returns when it fires."""
+        return self._issue(
+            "TIMER", name, {"type": "start_timer", "step_name": name, "delay_ms": max(0, int(seconds * 1000))}, "text"
+        )
+
+    def wait_for_signal(self, name: str, signal_name: str, *, decode: str = "text") -> Any:
+        """Block until a matching external signal arrives; return its payload."""
+        return self.wait_for_signal_async(name, signal_name, decode=decode).result()
+
+    def wait_for_signal_async(self, name: str, signal_name: str, *, decode: str = "text") -> Future:
+        """Start waiting for a signal and return at once."""
+        return self._issue(
+            "SIGNAL", name, {"type": "await_signal", "step_name": name, "signal_name": signal_name}, decode
+        )
+
+    def wait_all(self, *futures: Future) -> List[Any]:
+        """Wait for every future and return their results, in order."""
+        return [f.result() for f in futures]
+
+    def wait_any(self, *futures: Future) -> int:
+        """Wait until one of the futures has a result and return its index. When
+        several have one, the step history recorded first wins, so every replay
+        agrees::
+
+            reply = ctx.wait_for_signal_async("reply", "approved")
+            deadline = ctx.sleep_async("deadline", 48 * 3600)
+            if ctx.wait_any(reply, deadline) == 1:
+                ...  # timed out
+        """
+        best, best_id = -1, 0
+        for i, f in enumerate(futures):
+            rec = f._recorded()
+            if rec is not None and (best < 0 or rec.get("resolved_event_id", 0) < best_id):
+                best, best_id = i, rec.get("resolved_event_id", 0)
+        if best < 0:
+            raise _Yield()
+        return best
+
+    def get_version(self, change_id: str, min_supported: int, max_supported: int) -> int:
+        """Change workflow code while executions are in flight::
+
+            if ctx.get_version("add-fraud-check", DEFAULT_VERSION, 1) == 1:
+                ctx.activity("fraud-check", order)
+
+        An execution reaching this point for the first time records
+        max_supported and keeps it on every replay. One that ran past this point
+        under the old code gets DEFAULT_VERSION. A recorded version outside
+        [min_supported, max_supported] fails the execution.
+        """
+        v = self._versions.get(change_id)
+        if v is None:
+            seq = self._next + 1
+            rec = self._steps[seq - 1] if seq <= len(self._steps) else None
+            if rec is None:
+                self._next = seq
+                self._pending.append(
+                    {
+                        "type": "record_marker",
+                        "step_name": change_id,
+                        "sequence": seq,
+                        "marker": "version",
+                        "data": str(max_supported),
+                    }
+                )
+                v = max_supported
+            elif rec.get("kind") != "MARKER" or rec.get("marker") != "version" or rec.get("step_name") != change_id:
+                v = DEFAULT_VERSION  # this execution ran past here before the change
+            else:
+                self._next = seq
+                v = int(read_payload(rec, "output"))
+            self._versions[change_id] = v
+        if v < min_supported or v > max_supported:
+            raise _NonDeterminism(
+                f'non-determinism: execution recorded version {v} of "{change_id}", '
+                f"but the code supports {min_supported}..{max_supported}"
+            )
+        return v
+
+    def side_effect(self, name: str, fn: Callable[[], Any], *, decode: str = "text") -> Any:
+        """Run fn once, record its result, return the recorded result on every
+        replay. For small non-deterministic values; it must not fail or do I/O."""
+        seq = self._next + 1
+        if seq > len(self._steps):
+            self._next = seq
+            command = _put_payload(
+                {"type": "record_marker", "step_name": name, "sequence": seq, "marker": "side_effect"}, "data", fn()
+            )
+            self._pending.append(command)
+            return read_payload(command, "data", decode)  # what every replay will return
+        return self._issue("MARKER", name, None, decode).result()
+
+    def _issue(self, kind: str, name: str, command: Optional[dict], decode: str) -> Future:
+        """Give the next durable call its sequence, check it against history,
+        and start the step if history has none yet."""
+        self._next += 1
+        seq = self._next
+        recorded = self._steps[seq - 1] if seq <= len(self._steps) else None
+        if recorded is None:
+            command = dict(command or {})
+            command["sequence"] = seq
+            self._pending.append(command)
+        else:
+            # Determinism: the call being made now must be the step history
+            # recorded at this position.
+            marker_mismatch = kind == "MARKER" and recorded.get("marker") != "side_effect"
+            if recorded.get("kind") != kind or recorded.get("step_name") != name or marker_mismatch:
+                raise _NonDeterminism(
+                    f'non-determinism at step {seq}: code issued {kind} "{name}" but '
+                    f'history has {recorded.get("kind")} "{recorded.get("step_name")}"'
+                )
+        return Future(self, seq, name, decode)
+
+
+def decide(fn: Callable[[Context], Any], task: dict) -> dict:
+    """Replay a workflow function against a task and produce what happens next.
+
+    Pure: no I/O, no shared state. Returns ``{"commands": [...]}`` (empty when
+    the workflow is blocked on steps in flight) or ``{"replay_error": ...}``.
+    """
+    ctx = Context(task)
+    try:
+        output = fn(ctx)
+        return {"commands": ctx._pending + [_put_payload({"type": "complete_workflow"}, "output", output)]}
+    except _Yield:
+        return {"commands": list(ctx._pending)}
+    except _NonDeterminism as err:
+        return {"replay_error": str(err)}
+    except Exception as err:  # WorkflowFailure, uncaught ActivityFailure, bugs
+        return {"commands": ctx._pending + [{"type": "fail_workflow", "error": str(err) or repr(err)}]}
+
+
+def _accepts_two_args(fn: Callable[..., Any]) -> bool:
+    try:
+        params = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError):
+        return False
+    if any(p.kind == p.VAR_POSITIONAL for p in params):
+        return True
+    positional = [p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
+    return len(positional) >= 2
+
+
+class _HTTPError(Exception):
+    def __init__(self, status: int, message: str, body: Optional[dict] = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.body = body or {}
+
+
+class _Connection:
+    """Talks to whichever node currently serves requests. A 503 from a cluster
+    follower names the leader (``leader_http``); without a name, or when a node
+    is unreachable, it moves to the next address. ``epoch`` counts those moves
+    so the worker registers again: every new engine starts with none."""
+
+    def __init__(self, addresses: List[str], token: Optional[str] = None, ssl_context: Optional[ssl.SSLContext] = None):
+        if not addresses:
+            raise ValueError("workflowd: at least one address is required")
+        self.token = token
+        self._ssl = ssl_context
+        self.addrs = [a.rstrip("/") for a in addresses]
+        self.current = 0
+        self.epoch = 0
+        self._lock = threading.Lock()
+
+    @property
+    def base(self) -> str:
+        with self._lock:
+            return self.addrs[self.current]
+
+    def _move_on(self, frm: str, leader_http: str) -> None:
+        with self._lock:
+            self.epoch += 1
+            if self.addrs[self.current] != frm:
+                return  # another call already moved on
+            if leader_http:
+                url = f"{urllib.parse.urlsplit(frm).scheme}://{leader_http}"
+                if url not in self.addrs:
+                    self.addrs.append(url)
+                i = self.addrs.index(url)
+                if i != self.current:
+                    self.current = i
+                    return
+            self.current = (self.current + 1) % len(self.addrs)
+
+    def request(self, method: str, path: str, body: Optional[dict] = None, attempts: int = 12, timeout: float = 40.0):
+        backoff = 0.05
+        for attempt in range(1, attempts + 1):
+            frm = self.base
+            data = json.dumps(body).encode() if body is not None else None
+            headers = {"Content-Type": "application/json"}
+            if self.token:
+                headers["Authorization"] = f"Bearer {self.token}"
+            req = urllib.request.Request(frm + path, data=data, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=timeout, context=self._ssl) as res:
+                    if res.status == 204:
+                        return None  # long-poll expired
+                    raw = res.read()
+                    return json.loads(raw) if raw else {}
+            except urllib.error.HTTPError as err:
+                raw = err.read()
+                try:
+                    parsed = json.loads(raw) if raw else {}
+                except ValueError:
+                    parsed = {"error": raw.decode(errors="replace")}
+                if err.code != 503:
+                    raise _HTTPError(err.code, parsed.get("error", str(err)), parsed) from None
+                self._move_on(frm, parsed.get("leader_http") or "")
+                if attempt >= attempts:
+                    raise _HTTPError(503, parsed.get("error", "HTTP 503"), parsed) from None
+                if parsed.get("leader_http"):
+                    continue
+            except (urllib.error.URLError, OSError):
+                self._move_on(frm, "")
+                if attempt >= attempts:
+                    raise
+            time.sleep(backoff)
+            backoff = min(backoff * 2, 1.0)
+        return None
+
+
+class Worker:
+    """Connects to an engine, registers workflow types, and serves both
+    workflow decisions and activity executions."""
+
+    def __init__(
+        self,
+        address: str = "http://localhost:8233",
+        worker_id: Optional[str] = None,
+        sdk: str = SDK_VERSION,
+        token: Optional[str] = None,
+        ca_file: Optional[str] = None,
+        *,
+        addresses: Optional[List[str]] = None,
+        activity_concurrency: int = 4,
+        workflow_concurrency: int = 2,
+    ):
+        """``token`` is sent as ``Authorization: Bearer <token>`` for an engine
+        started with --auth-token-file. ``ca_file`` trusts a private CA for an
+        https address; without it the system trust store is used. ``addresses``
+        lists every cluster node (it replaces ``address``)."""
+        ctx = ssl.create_default_context(cafile=ca_file) if ca_file else None
+        self.conn = _Connection(addresses or [address], token, ctx)
+        self.worker_id = worker_id or f"py-worker-{random.randrange(16**8):08x}"
+        self.sdk = sdk
+        self.workflows: Dict[str, Callable[[Context], Any]] = {}
+        self.activities: Dict[str, Callable[..., Any]] = {}
+        self._activity_decode: Dict[str, str] = {}
+        self._activity_takes_info: Dict[str, bool] = {}
+        self.activity_concurrency = activity_concurrency
+        self.workflow_concurrency = workflow_concurrency
+        self._registered_epoch = -1
+        self._stop = threading.Event()
+
+    @property
+    def address(self) -> str:
+        """The base URL of the node currently in use."""
+        return self.conn.base
+
+    # -- registration (usable as decorators) --
+
+    def workflow(self, workflow_type: str):
+        def wrap(fn):
+            self.workflows[workflow_type] = fn
+            return fn
+
+        return wrap
+
+    def activity(self, step_name: str, *, decode: str = "text"):
+        """Register an activity. fn(input) gets the input decoded per
+        ``decode``; fn(input, info) also gets the task, whose ``lease_lost``
+        event is set if the engine reassigns the work."""
+
+        def wrap(fn):
+            self.activities[step_name] = fn
+            self._activity_decode[step_name] = decode
+            self._activity_takes_info[step_name] = _accepts_two_args(fn)
+            return fn
+
+        return wrap
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    # -- client helpers --
+
+    def register(self) -> None:
+        """Tell the engine which workflow types this worker can replay."""
+        if not self.workflows:
+            return
+        epoch = self.conn.epoch
+        self.conn.request(
+            "POST",
+            "/api/workflow-types",
+            {"workflow_types": list(self.workflows), "worker_id": self.worker_id, "sdk": self.sdk},
+        )
+        # The epoch from before the call: if the call moved nodes, the next
+        # poll registers again, which is harmless.
+        self._registered_epoch = epoch
+
+    def start_workflow(self, workflow_type: str, payload: Any = "", workflow_id: str = "") -> str:
+        # Chosen here so a retry after a lost reply cannot start a second execution.
+        wid = workflow_id or f"{workflow_type}-{random.randrange(16**16):016x}"
+        try:
+            self.conn.request(
+                "POST", "/api/workflows", _put_payload({"type": workflow_type, "workflow_id": wid}, "input", payload)
+            )
+        except _HTTPError as err:
+            if not (err.status == 409 and not workflow_id):
+                raise
+        return wid
+
+    def signal(self, workflow_id: str, name: str, payload: Any = "", request_id: Optional[str] = None) -> None:
+        """Send a signal. It is recorded once even if the request is retried
+        (after a lost reply or a leader change): every attempt carries the same
+        idempotency key, ``request_id`` or a random one."""
+        body = {"name": name, "request_id": request_id or f"{random.randrange(16**16):016x}"}
+        self.conn.request(
+            "POST",
+            f"/api/workflows/{urllib.parse.quote(workflow_id, safe='')}/signal",
+            _put_payload(body, "payload", payload),
+        )
+
+    def describe(self, workflow_id: str) -> dict:
+        return self.conn.request("GET", f"/api/workflows/{urllib.parse.quote(workflow_id, safe='')}")
+
+    # -- serving loops --
+
+    def _workflow_loop(self) -> None:
+        types = urllib.parse.quote(",".join(self.workflows))
+        wid = urllib.parse.quote(self.worker_id)
+        while not self._stop.is_set():
+            try:
+                if self._registered_epoch != self.conn.epoch:
+                    self.register()
+                task = self.conn.request("GET", f"/api/workflow-tasks?types={types}&worker_id={wid}", attempts=1)
+            except Exception:
+                time.sleep(0.2)  # engine unreachable or turned us away; retry
+                continue
+            if not task:
+                continue
+
+            fn = self.workflows.get(task.get("workflow_type", ""))
+            if fn is None:
+                result = {"replay_error": f'no workflow registered for type {task.get("workflow_type")}'}
+            else:
+                result = decide(fn, task)
+
+            body = {
+                "workflow_id": task["workflow_id"],
+                "task_token": task["task_token"],
+                "replay_error": result.get("replay_error", ""),
+            }
+            commands = result.get("commands") or []
+            # One command travels in the field every engine version understands.
+            if len(commands) > 1:
+                body["commands"] = commands
+            else:
+                body["command"] = commands[0] if commands else None
+            try:
+                self.conn.request("POST", "/api/workflow-tasks/complete", body, attempts=3)
+            except Exception as err:
+                # 409 = the decision went stale because history moved on.
+                # Polling again is the correct response, so stay quiet.
+                if getattr(err, "status", None) != 409:
+                    print(f"[workflowd] complete failed: {err}")
+
+    def _activity_loop(self) -> None:
+        # Name our activities so the engine never hands us another worker's step.
+        names = urllib.parse.quote(",".join(self.activities))
+        wid = urllib.parse.quote(self.worker_id)
+        while not self._stop.is_set():
+            try:
+                task = self.conn.request("GET", f"/api/activity-tasks?activities={names}&worker_id={wid}", attempts=1)
+            except Exception:
+                time.sleep(0.2)
+                continue
+            if task:
+                self._execute(task)
+
+    def _execute(self, task: dict) -> None:
+        step = task["step_name"]
+        fn = self.activities.get(step)
+        lease_lost = threading.Event()
+        stop_beats = self._heartbeat(task, lease_lost)
+        result = {
+            "workflow_id": task["workflow_id"],
+            "step_name": step,
+            "sequence": task["sequence"],
+            "lease_token": task["lease_token"],
+        }
+        try:
+            if fn is None:
+                raise RuntimeError(f'no activity registered for step "{step}"')
+            arg = read_payload(task, "input", self._activity_decode.get(step, "text"))
+            if self._activity_takes_info.get(step, False):
+                out = fn(arg, dict(task, lease_lost=lease_lost))
+            else:
+                out = fn(arg)
+            _put_payload(result, "output", out)
+        except Exception as err:
+            result["error"] = str(err) or repr(err)
+        finally:
+            stop_beats()
+        try:
+            self.conn.request("POST", "/api/activity-tasks/complete", result, attempts=3)
+        except Exception as err:
+            if getattr(err, "status", None) != 409:  # lost lease: task was reassigned
+                print(f"[workflowd] activity complete failed: {err}")
+
+    def _heartbeat(self, task: dict, lease_lost: threading.Event) -> Callable[[], None]:
+        """Extend the lease every third of its duration until stopped; a 409
+        means the lease is gone, so lease_lost is set."""
+        every = (task.get("lease_duration_ms") or 0) / 3000.0
+        if every <= 0:
+            return lambda: None
+        done = threading.Event()
+
+        def beat() -> None:
+            body = {"workflow_id": task["workflow_id"], "lease_token": task["lease_token"], "worker_id": self.worker_id}
+            while not done.wait(every):
+                try:
+                    self.conn.request("POST", "/api/activity-tasks/heartbeat", body, attempts=2)
+                except Exception as err:
+                    if getattr(err, "status", None) == 409:
+                        lease_lost.set()
+                        return
+
+        t = threading.Thread(target=beat, daemon=True, name="workflowd-heartbeat")
+        t.start()
+
+        def stop() -> None:
+            done.set()
+            t.join()
+
+        return stop
+
+    def run(self, block: bool = True) -> None:
+        """Register, then serve workflow decisions and activities."""
+        self._stop.clear()
+        threads = []
+        if self.workflows:
+            try:
+                self.register()
+            except _HTTPError as err:
+                if err.status != 503:
+                    raise  # a refused type is a bug to surface
+            except OSError:
+                pass  # not up yet: the workflow loop keeps trying
+            for i in range(self.workflow_concurrency):
+                threads.append(threading.Thread(target=self._workflow_loop, daemon=True, name=f"workflowd-decisions-{i}"))
+        # An empty filter means "any activity", so a worker with none must not poll.
+        if self.activities:
+            for i in range(self.activity_concurrency):
+                threads.append(threading.Thread(target=self._activity_loop, daemon=True, name=f"workflowd-activities-{i}"))
+        for t in threads:
+            t.start()
+        if not block:
+            return
+        try:
+            while not self._stop.is_set():
+                time.sleep(0.2)
+        except KeyboardInterrupt:
+            self.stop()