durable-workflow 2.7.0__tar.gz → 2.8.0__tar.gz

{durable_workflow-2.7.0/src/durable_workflow.egg-info → durable_workflow-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.7.0
+Version: 2.8.0
 Summary: Python client and worker SDK for Durable Workflow Cloud and self-hosted Server
 Author: Durable Workflow Contributors
 License-Expression: MIT
@@ -185,6 +185,17 @@ independently of application heartbeats. Existing terminal cancellation remains
 available. See the [cancellation guide](docs/cooperative-cancellation-design.md)
 for immutable context, operation policies, shielded cleanup and recovery.
 
+Both `await activity.context().heartbeat()` and synchronous
+`activity.context().heartbeat_sync()` stop at an explicit Server refusal.
+They raise `ActivityLeaseAuthorityLost` with its original `.reason` for an
+elapsed deadline, closed attempt or closed run. Cancellation continues to raise
+`ActivityCancelled`. The worker submits no result or failure for an attempt
+whose heartbeat refused continuation, even if application code catches that
+exception. A heartbeat check acts only when called. Code that never heartbeats
+can continue until it returns, subject to independent lease/cancellation
+supervision; a running native thread cannot be forcibly stopped or its effects
+undone by the SDK.
+
 ## Development
 
 The installed `durable-workflow-replay-conformance` command runs an offline

{durable_workflow-2.7.0 → durable_workflow-2.8.0}/README.md

@@ -142,6 +142,17 @@ independently of application heartbeats. Existing terminal cancellation remains
 available. See the [cancellation guide](docs/cooperative-cancellation-design.md)
 for immutable context, operation policies, shielded cleanup and recovery.
 
+Both `await activity.context().heartbeat()` and synchronous
+`activity.context().heartbeat_sync()` stop at an explicit Server refusal.
+They raise `ActivityLeaseAuthorityLost` with its original `.reason` for an
+elapsed deadline, closed attempt or closed run. Cancellation continues to raise
+`ActivityCancelled`. The worker submits no result or failure for an attempt
+whose heartbeat refused continuation, even if application code catches that
+exception. A heartbeat check acts only when called. Code that never heartbeats
+can continue until it returns, subject to independent lease/cancellation
+supervision; a running native thread cannot be forcibly stopped or its effects
+undone by the SDK.
+
 ## Development
 
 The installed `durable-workflow-replay-conformance` command runs an offline

{durable_workflow-2.7.0 → durable_workflow-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.7.0"
+version = "2.8.0"
 description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -75,8 +75,8 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
 durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"
 
 [tool.durable-workflow]
-product-train = "2.7.0"
-registry-version = "2.7.0"
+product-train = "2.8.0"
+registry-version = "2.8.0"
 supported-server-versions = "2.8.0"
 worker-protocol-version = "1.20"
 control-plane-version = "2"

durable_workflow-2.8.0/src/durable_workflow/_activity_lease.py

@@ -0,0 +1,325 @@
+"""Runtime lease maintenance for one original activity delivery."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+
+from .errors import ActivityLeaseAuthorityLost, ServerError
+
+_T = TypeVar("_T")
+_UTC6 = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z\Z")
+
+
+def _timestamp(value: Any) -> datetime:
+    if not isinstance(value, str) or _UTC6.fullmatch(value) is None:
+        raise ValueError("activity timing must be UTC with six fractional digits")
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def activity_lease_renewal_supported(client: Any) -> bool:
+    """Use the same cached discovery that validates actual renewal requests."""
+    info = getattr(client, "_cluster_info", None)
+    protocol = info.get("worker_protocol") if isinstance(info, Mapping) else None
+    capabilities = protocol.get("server_capabilities") if isinstance(protocol, Mapping) else None
+    return isinstance(capabilities, Mapping) and capabilities.get("activity_lease_renewal") is True
+
+
+def _heartbeat_terms(task: Mapping[str, Any], deadlines: Mapping[str, Any],
+                     reference: datetime) -> tuple[datetime | None, int | None]:
+    heartbeat = _timestamp(deadlines["heartbeat"]) if deadlines.get("heartbeat") is not None else None
+    policy = task.get("retry_policy")
+    interval = policy.get("heartbeat_timeout") if isinstance(policy, Mapping) else None
+    if heartbeat is not None and (type(interval) is not int or interval <= 0):
+        raise ValueError("missing recorded activity heartbeat interval")
+    interval = interval if type(interval) is int and interval > 0 else None
+    if heartbeat is not None and interval is not None and heartbeat - reference > timedelta(seconds=interval):
+        raise ValueError("activity heartbeat deadline predates its claimed progress")
+    return heartbeat, interval
+
+
+@dataclass
+class ActivityLeaseAuthority:
+    client: Any
+    namespace: str
+    identity: dict[str, Any]
+    task_identity: dict[str, Any]
+    captured_at: float
+    lease_until: float
+    business_until: float | None
+    heartbeat_until: float | None
+    heartbeat_timeout: int | None
+    server_time: datetime
+    lease_expiry: datetime
+    heartbeat_time: datetime | None
+    heartbeat_deadline: datetime | None
+    last_renewal: tuple[datetime, datetime, float] | None = None
+    lost_reason: str | None = field(default=None, init=False)
+
+    @classmethod
+    async def confirm_delivery(cls, client: Any, namespace: str, task: Mapping[str, Any], *, owner: str,
+                               task_queue: str, server_time: Any) -> ActivityLeaseAuthority:
+        # A long poll may wait before a task or its lease exists. Establish the
+        # first execution budget with a separate, original-claim confirmation;
+        # its entire round trip is charged and it cannot revive an expired lease.
+        provisional = cls.delivery(client, namespace, task, owner=owner, task_queue=task_queue,
+                                   server_time=server_time, request_started=time.monotonic())
+        started = time.monotonic()
+        try:
+            reply = await client.renew_activity_task_lease(
+                task_id=provisional.task_id, activity_attempt_id=provisional.identity["activity_attempt_id"],
+                lease_owner=owner, timeout=min(5.0, provisional.remaining()),
+            )
+            provisional.acknowledge(reply, started)
+        except ActivityLeaseAuthorityLost:
+            raise
+        except Exception as error:
+            reason = error.reason() if isinstance(error, ServerError) else None
+            raise ActivityLeaseAuthorityLost(
+                provisional.task_id, reason or "activity_initial_lease_unavailable",
+            ) from error
+        observed = dict(task)
+        observed["lease_expires_at"] = reply["lease_expires_at"]
+        if provisional.heartbeat_deadline is not None:
+            observed["deadlines"] = {**dict(task.get("deadlines", {})),
+                                     "heartbeat": provisional.heartbeat_deadline.isoformat(
+                                         timespec="microseconds").replace("+00:00", "Z")}
+        return cls.delivery(client, namespace, observed, owner=owner, task_queue=task_queue,
+                            server_time=reply["server_time"], request_started=started)
+
+    @classmethod
+    def delivery(cls, client: Any, namespace: str, task: Mapping[str, Any], *, owner: str,
+                 task_queue: str, server_time: Any, request_started: float) -> ActivityLeaseAuthority:
+        task_id = str(task.get("task_id") or "")
+        try:
+            keys = ("task_id", "workflow_id", "run_id", "activity_execution_id", "activity_attempt_id",
+                    "lease_owner", "task_queue")
+            if (any(not isinstance(task.get(key), str) or not task[key] for key in keys)
+                    or task["lease_owner"] != owner or task["task_queue"] != task_queue
+                    or task.get("namespace", namespace) != namespace
+                    or type(task.get("attempt_number")) is not int or task["attempt_number"] < 1):
+                raise ValueError("invalid original activity identity")
+            reference = _timestamp(server_time)
+            expiry = _timestamp(task.get("lease_expires_at"))
+            duration = (expiry - reference).total_seconds()
+            if not 0 < duration <= 86400 or not 0 <= request_started <= time.monotonic():
+                raise ValueError("invalid original activity lease")
+            deadlines = task.get("deadlines", {})
+            if not isinstance(deadlines, Mapping):
+                raise ValueError("invalid activity deadlines")
+            bounds = [_timestamp(deadlines[key]) for key in ("start_to_close", "schedule_to_close", "run", "execution")
+                      if deadlines.get(key) is not None]
+            business = request_started + (min(bounds) - reference).total_seconds() if bounds else None
+            heartbeat, interval = _heartbeat_terms(task, deadlines, reference)
+            result = cls(
+                client, namespace,
+                {"workflow_task_id": task["task_id"], "workflow_instance_id": task["workflow_id"],
+                 "workflow_run_id": task["run_id"], "activity_execution_id": task["activity_execution_id"],
+                 "activity_attempt_id": task["activity_attempt_id"], "attempt_number": task["attempt_number"],
+                 "lease_owner": owner},
+                {key: task[key] for key in (*keys, "attempt_number")},
+                request_started, request_started + duration, business,
+                request_started + (heartbeat - reference).total_seconds() if heartbeat is not None else None,
+                interval, reference, expiry,
+                heartbeat - timedelta(seconds=interval) if heartbeat is not None and interval is not None else None,
+                heartbeat,
+            )
+        except (KeyError, TypeError, ValueError, OverflowError) as error:
+            raise ActivityLeaseAuthorityLost(task_id, "invalid_activity_claim") from error
+        result.remaining()
+        return result
+
+    @property
+    def task_id(self) -> str:
+        return str(self.identity["workflow_task_id"])
+
+    def matches(self, client: Any, namespace: str, task: Mapping[str, Any], owner: str, task_queue: str) -> bool:
+        return (self.client is client and self.namespace == namespace and self.identity["lease_owner"] == owner
+                and self.task_identity["task_queue"] == task_queue
+                and type(task.get("attempt_number")) is int
+                and all(task.get(key) == value for key, value in self.task_identity.items()))
+
+    def governs(self, client: Any, namespace: str, path: str) -> bool:
+        prefixes = (f"/worker/activity-tasks/{self.task_id}/",
+                    f"/worker/activity-tasks/{quote(self.task_id, safe='')}/")
+        return (self.client is client and self.namespace == namespace
+                and (any(path == prefix + action for prefix in prefixes
+                         for action in ("complete", "fail", "heartbeat", "renew-lease"))
+                     or path == "/external-payloads/v1"))
+
+    def acknowledge_progress(self, reply: Any, request_started: float) -> None:
+        """Use an actual application heartbeat, never a runtime liveness ping.
+
+        The existing heartbeat contract records last_heartbeat_at at the write
+        and resets its original recorded timeout interval from that instant.
+        Charging the whole request duration consumes storage/network latency.
+        """
+        self.remaining()
+        received = time.monotonic()
+        try:
+            expected = {"task_id": self.task_id, "activity_attempt_id": self.identity["activity_attempt_id"],
+                        "lease_owner": self.identity["lease_owner"]}
+            if (not isinstance(reply, Mapping) or reply.get("heartbeat_recorded") is not True
+                    or reply.get("can_continue") is not True or reply.get("cancel_requested") is not False
+                    or reply.get("reason") is not None
+                    or any(reply.get(key) != value for key, value in expected.items())
+                    or not self.captured_at <= request_started <= received):
+                raise ValueError("heartbeat did not confirm the original activity")
+            progress = _timestamp(reply.get("last_heartbeat_at"))
+            expiry = _timestamp(reply.get("lease_expires_at"))
+            duration = (expiry - progress).total_seconds()
+            if not 0 < duration <= 86400:
+                raise ValueError("invalid heartbeat lease grant")
+            if self.heartbeat_time is not None and progress <= self.heartbeat_time:
+                return
+            if request_started + duration <= received:
+                raise ValueError("heartbeat lease grant was consumed in transport")
+            if self.heartbeat_timeout is not None:
+                until = request_started + self.heartbeat_timeout
+                if until <= received:
+                    raise ValueError("heartbeat progress window was consumed in transport")
+                self.heartbeat_until = max(self.heartbeat_until or until, until)
+                self.heartbeat_deadline = progress + timedelta(seconds=self.heartbeat_timeout)
+            self.heartbeat_time = progress
+            self.lease_until = max(self.lease_until, request_started + duration)
+            self.lease_expiry = max(self.lease_expiry, expiry)
+        except (TypeError, ValueError, OverflowError) as error:
+            self.lost_reason = "invalid_activity_heartbeat"
+            raise ActivityLeaseAuthorityLost(self.task_id, self.lost_reason) from error
+
+    def remaining(self) -> float:
+        if self.lost_reason is not None:
+            raise ActivityLeaseAuthorityLost(self.task_id, self.lost_reason)
+        bounds = [self.lease_until, *(value for value in (self.business_until, self.heartbeat_until)
+                                     if value is not None)]
+        remaining = min(bounds) - time.monotonic()
+        if remaining <= 0:
+            self.lost_reason = "activity_execution_budget_expired"
+            raise ActivityLeaseAuthorityLost(self.task_id, self.lost_reason)
+        return remaining
+
+    def acknowledge(self, reply: Any, request_started: float) -> None:
+        self.remaining()
+        received = time.monotonic()
+        try:
+            if (not isinstance(reply, Mapping) or reply.get("lease_renewed") is not True
+                    or reply.get("can_continue") is not True or reply.get("cancel_requested") is not False
+                    or reply.get("heartbeat_recorded") is not False or reply.get("reason") is not None
+                    or type(reply.get("attempt_number")) is not int
+                    or any(reply.get(key) != value for key, value in self.identity.items())
+                    or not self.captured_at <= request_started <= received):
+                raise ValueError("renewal did not preserve the original activity claim")
+            server = _timestamp(reply.get("server_time"))
+            expiry = _timestamp(reply.get("lease_expires_at"))
+            duration = (expiry - server).total_seconds()
+            if not 0 < duration <= 86400 or request_started + duration <= received:
+                raise ValueError("renewal did not prove a live grant")
+            if (self.heartbeat_time is not None and server < self.heartbeat_time and expiry <= self.lease_expiry):
+                # An independently acknowledged application heartbeat can
+                # overtake an in-flight renewal. Its older reply grants nothing.
+                return
+            if expiry < self.lease_expiry or server < self.server_time:
+                raise ValueError("renewal predates the confirmed grant")
+            confirmation = (server, expiry, request_started)
+            if self.last_renewal is not None and server <= self.last_renewal[0]:
+                if confirmation == self.last_renewal:
+                    return
+                raise ValueError("replayed activity renewal")
+            self.lease_until = max(self.lease_until, request_started + duration)
+            self._observe_progress(reply, server, request_started, received)
+            self.server_time, self.lease_expiry, self.last_renewal = server, expiry, confirmation
+        except (TypeError, ValueError, OverflowError) as error:
+            self.lost_reason = "invalid_activity_renewal"
+            raise ActivityLeaseAuthorityLost(self.task_id, self.lost_reason) from error
+
+    def _observe_progress(self, reply: Mapping[str, Any], server: datetime, started: float, received: float) -> None:
+        if self.heartbeat_until is None or self.heartbeat_timeout is None:
+            return
+        try:
+            progress = _timestamp(reply.get("last_heartbeat_at"))
+            deadline = _timestamp(reply.get("heartbeat_deadline_at"))
+        except (TypeError, ValueError):
+            return
+        until = started + (deadline - server).total_seconds()
+        if (progress <= server < deadline and until > received
+                and (self.heartbeat_time is None or progress > self.heartbeat_time)
+                and (self.heartbeat_deadline is None or deadline > self.heartbeat_deadline)
+                and deadline - progress == timedelta(seconds=self.heartbeat_timeout)):
+            self.heartbeat_until = max(self.heartbeat_until, until)
+            self.heartbeat_time, self.heartbeat_deadline = progress, deadline
+
+    async def renew(self) -> bool:
+        started = time.monotonic()
+        try:
+            reply = await asyncio.wait_for(self.client.renew_activity_task_lease(
+                task_id=self.task_id, activity_attempt_id=self.identity["activity_attempt_id"],
+                lease_owner=self.identity["lease_owner"], timeout=min(5.0, self.remaining()),
+            ), timeout=min(5.0, self.remaining()))
+            self.acknowledge(reply, started)
+            return True
+        except ActivityLeaseAuthorityLost:
+            raise
+        except Exception as error:
+            if (isinstance(error, (httpx.TransportError, asyncio.TimeoutError))
+                    or isinstance(error, ServerError) and (error.status >= 500 or error.status == 429)):
+                # A failed exchange grants nothing. The existing lease may
+                # still authorize work until its original local bound.
+                self.remaining()
+                return False
+            self.lost_reason = "activity_renewal_unavailable"
+            raise ActivityLeaseAuthorityLost(self.task_id, self.lost_reason) from error
+
+    async def _maintain(self, stopped: asyncio.Event) -> None:
+        confirmed = True
+        while not stopped.is_set():
+            delay = min(30.0 if confirmed else 1.0, max(0.0, self.lease_until - time.monotonic()) / 3)
+            if self.heartbeat_timeout is not None:
+                delay = min(delay, self.heartbeat_timeout / 3)
+            await asyncio.sleep(min(delay, self.remaining()))
+            if stopped.is_set():
+                return
+            confirmed = await self.renew()
+
+    async def run(self, operation: Callable[[], Awaitable[_T]]) -> _T:
+        self.remaining()
+        stopped = asyncio.Event()
+        execution = asyncio.ensure_future(operation())
+        maintenance = asyncio.create_task(self._maintain(stopped))
+        try:
+            while True:
+                done, _ = await asyncio.wait({execution, maintenance}, timeout=self.remaining(),
+                                             return_when=asyncio.FIRST_COMPLETED)
+                if maintenance in done:
+                    await maintenance
+                    raise ActivityLeaseAuthorityLost(self.task_id, "activity_renewal_stopped")
+                if execution in done:
+                    result = await execution
+                    self.remaining()
+                    return result
+        except BaseException:
+            self.lost_reason = self.lost_reason or "activity_execution_abandoned"
+            raise
+        finally:
+            # An I/O wrapper may complete concurrently with cancel() and consume
+            # that cancellation. The settled scope must still stop renewing.
+            stopped.set()
+            # A Python thread may continue after cancellation. Its existing
+            # executor keeps the physical slot until it actually exits, while
+            # this context independently fences every late HTTP publication.
+            for future in (execution, maintenance):
+                future.cancel()
+            await asyncio.gather(execution, maintenance, return_exceptions=True)
+
+
+current_activity_authority: ContextVar[ActivityLeaseAuthority | None] = ContextVar(
+    "activity_lease_authority", default=None,
+)

{durable_workflow-2.7.0 → durable_workflow-2.8.0}/src/durable_workflow/activity.py

@@ -7,7 +7,8 @@ from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
-from .errors import ActivityCancelled
+from ._activity_lease import current_activity_authority
+from .errors import ActivityCancelled, ActivityLeaseAuthorityLost
 
 if TYPE_CHECKING:
     from .client import Client
@@ -45,6 +46,7 @@ class ActivityContext:
         self._client = client
         self._heartbeat_callback = heartbeat_callback
         self._cancel_requested = False
+        self._cannot_continue_reason: str | None = None
         try:
             self._event_loop: asyncio.AbstractEventLoop | None = asyncio.get_running_loop()
         except RuntimeError:
@@ -61,7 +63,7 @@ class ActivityContext:
         return self._cancel_requested
 
     def heartbeat_sync(self, details: dict[str, Any] | None = None) -> None:
-        """Heartbeat from a synchronous activity thread and observe cancellation.
+        """Heartbeat from a synchronous activity thread and check attempt authority.
 
         The request runs on the worker's event loop using the original attempt
         and client. Async handlers must use ``await heartbeat()`` instead.
@@ -84,7 +86,7 @@ class ActivityContext:
         pending.result()
 
     async def heartbeat(self, details: dict[str, Any] | None = None) -> None:
-        """Report liveness to the server and check for a cancellation request.
+        """Report progress and check cancellation and continued attempt authority.
 
         Long-running activities should call ``heartbeat()`` periodically so the
         server can distinguish a slow-but-alive attempt from a dead worker.
@@ -94,7 +96,12 @@ class ActivityContext:
         Raises :class:`~durable_workflow.errors.ActivityCancelled` when the
         owning workflow has requested cancellation, so the activity can exit
         cleanly at its next natural break point.
+
+        Raises :class:`~durable_workflow.errors.ActivityLeaseAuthorityLost`
+        with the original Server reason when the attempt cannot continue,
+        including an elapsed deadline, closed attempt or closed run.
         """
+        self._raise_if_cannot_continue()
         if self._heartbeat_callback is not None:
             try:
                 await self._heartbeat_callback(details)
@@ -111,6 +118,21 @@ class ActivityContext:
         if isinstance(resp, dict) and resp.get("cancel_requested"):
             self._cancel_requested = True
             raise ActivityCancelled()
+        if isinstance(resp, dict) and resp.get("can_continue") is False:
+            reason = resp.get("reason")
+            self._cannot_continue_reason = reason if isinstance(reason, str) and reason else "activity_cannot_continue"
+            self._raise_if_cannot_continue()
+
+    def _raise_if_cannot_continue(self) -> None:
+        if self._cannot_continue_reason is not None:
+            authority = current_activity_authority.get()
+            if (authority is not None and authority.client is self._client
+                    and authority.task_id == self._info.task_id
+                    and authority.identity["activity_attempt_id"] == self._info.activity_attempt_id
+                    and authority.identity["attempt_number"] == self._info.attempt_number
+                    and authority.identity["lease_owner"] == self._info.worker_id):
+                authority.lost_reason = authority.lost_reason or self._cannot_continue_reason
+            raise ActivityLeaseAuthorityLost(self._info.task_id, self._cannot_continue_reason)
 
 
 def context() -> ActivityContext:

{durable_workflow-2.7.0 → durable_workflow-2.8.0}/src/durable_workflow/client.py

@@ -39,6 +39,7 @@ from urllib.parse import quote, unquote, urlencode, urlsplit
 import httpx
 
 from . import serializer
+from ._activity_lease import ActivityLeaseAuthority, current_activity_authority
 from ._cancellation_scope import CancellationScopeOpenReceipt, scope_identity
 from ._cancellation_scope_history import (
     CancellationScopeBudget,
@@ -1871,8 +1872,14 @@ class Client:
             raise ValueError("cluster discovery credentials can only authorize /cluster/info")
 
         query_poll = worker and path == "/worker/query-tasks/poll"
+        activity_poll = worker and path == "/worker/activity-tasks/poll"
         if query_poll:
             current_query_authority.set(None)
+        if activity_poll:
+            current_activity_authority.set(None)
+        activity_authority = current_activity_authority.get()
+        if worker and activity_authority is not None and activity_authority.governs(self, self.namespace, path):
+            activity_authority.remaining()
         request_json = json
         if (
             not discovery
@@ -1904,14 +1911,20 @@ class Client:
         plane = "worker" if worker or discovery_uses_worker_token else "control"
         status_code = "none"
         outcome = "pending"
+        request_started = time.monotonic()
 
         async def _do_request() -> httpx.Response:
+            nonlocal request_started
+            request_started = time.monotonic()
+            request_timeout = self.timeout if timeout is None else timeout
+            if worker and activity_authority is not None and activity_authority.governs(self, self.namespace, path):
+                request_timeout = min(request_timeout, activity_authority.remaining())
             resp = await self._http.request(
                 method,
                 f"/api{path}",
                 headers=self._discovery_headers() if discovery else self._headers(worker=worker),
                 json=request_json,
-                timeout=self.timeout if timeout is None else timeout,
+                timeout=request_timeout,
             )
             # Raise HTTPStatusError for 4xx/5xx so retry policy can catch it
             resp.raise_for_status()
@@ -1936,11 +1949,28 @@ class Client:
                 outcome = "ok"
                 return None
             result = resp.json()
+            if (worker and activity_authority is not None
+                    and activity_authority.governs(self, self.namespace, path)
+                    and path.endswith("/heartbeat") and isinstance(result, dict)
+                    and result.get("heartbeat_recorded") is True):
+                activity_authority.acknowledge_progress(result, request_started)
+            if activity_poll and isinstance(result, dict) and isinstance(result.get("task"), dict):
+                capabilities = result.get("server_capabilities")
+                if isinstance(capabilities, dict) and capabilities.get("activity_lease_renewal") is True:
+                    activity_authority = await ActivityLeaseAuthority.confirm_delivery(
+                        self, self.namespace, result["task"], owner=request_json["worker_id"],
+                        task_queue=request_json["task_queue"], server_time=result.get("server_time"),
+                    )
+                    current_activity_authority.set(activity_authority)
             query_authority = None
             if query_poll and isinstance(result, dict) and isinstance(result.get("task"), dict):
                 query_authority = await self._query_delivery_authority(result["task"], request_json)
                 current_query_authority.set(query_authority)
-            if not discovery and _contains_runtime_payload_envelope(result):
+            if activity_authority is not None and activity_poll and _contains_runtime_payload_envelope(result):
+                result = await activity_authority.run(
+                    lambda: self._resolve_activity_claim_payloads(result, worker=worker),
+                )
+            elif not discovery and _contains_runtime_payload_envelope(result):
                 transport = (await query_authority.run(self._runtime_external_payload_transport)
                              if query_authority is not None else await self._runtime_external_payload_transport())
                 if transport is None:
@@ -1957,6 +1987,8 @@ class Client:
                         result, worker=worker, transport=transport, path=path, request_json=request_json,
                     )
             result = self._hydrate_result_envelopes(result)
+            if activity_poll and activity_authority is not None:
+                activity_authority.remaining()
             if query_authority is not None:
                 await query_authority.confirm()
             outcome = "ok"
@@ -1976,6 +2008,12 @@ class Client:
             self.metrics.increment(CLIENT_REQUESTS, tags=tags)
             self.metrics.record(CLIENT_REQUEST_DURATION_SECONDS, time.perf_counter() - start, tags=tags)
 
+    async def _resolve_activity_claim_payloads(self, value: Any, *, worker: bool) -> Any:
+        transport = await self._runtime_external_payload_transport()
+        if transport is None:
+            raise ExternalPayloadUnsupported("activity payload reference has no authenticated runtime transport")
+        return await self._resolve_runtime_payloads(value, worker=worker, transport=transport, resolved={})
+
     async def _runtime_external_payload_transport(
         self,
     ) -> _RuntimeExternalPayloadTransport | None:
@@ -6160,6 +6198,48 @@ class Client:
             "POST", f"/worker/activity-tasks/{task_id}/fail", worker=True, json=body
         )
 
+    async def renew_activity_task_lease(
+        self,
+        *,
+        task_id: str,
+        activity_attempt_id: str,
+        lease_owner: str,
+        timeout: float = 5.0,
+    ) -> Any:
+        """Renew one live activity claim without recording application progress.
+
+        Requires affirmative ``activity_lease_renewal`` discovery. The caller
+        must validate the returned original identity and grant before using it.
+        This neither revives an expired claim nor extends business timeouts.
+        Discovery, retries and transport share the supplied bounded window.
+        """
+        for field, value in (
+            ("task_id", task_id), ("activity_attempt_id", activity_attempt_id), ("lease_owner", lease_owner),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"{field} must be a non-empty string")
+        if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 0 < timeout <= 5:
+            raise ValueError("activity lease renewal timeout must be greater than zero and at most five seconds")
+
+        async def renew() -> Any:
+            operation = "Client.renew_activity_task_lease"
+            path = "worker_protocol.server_capabilities.activity_lease_renewal"
+            info = await self._runtime_discovery(operation=operation, required_path=path)
+            protocol = info.get("worker_protocol")
+            capabilities = protocol.get("server_capabilities") if isinstance(protocol, dict) else None
+            supported = capabilities.get("activity_lease_renewal") if isinstance(capabilities, dict) else None
+            if supported is False:
+                raise RuntimeCapabilityUnsupported(operation, path, f"This runtime does not support {path}.")
+            if supported is not True:
+                raise RuntimeDiscoveryUnavailable(operation, path, f"Runtime discovery must advertise {path}=true.")
+
+            return await self._request(
+                "POST", f"/worker/activity-tasks/{quote(task_id, safe='')}/renew-lease", worker=True,
+                json={"activity_attempt_id": activity_attempt_id, "lease_owner": lease_owner}, timeout=timeout,
+            )
+
+        return await asyncio.wait_for(renew(), timeout=timeout)
+
     async def activity_task_status(
         self,
         *,
@@ -6305,7 +6385,8 @@ class Client:
         Worker-plane endpoint. Most code calls
         :meth:`~durable_workflow.ActivityContext.heartbeat` instead, which
         additionally raises :class:`~durable_workflow.errors.ActivityCancelled`
-        when the server reports the activity should stop.
+        for cancellation or :class:`~durable_workflow.errors.ActivityLeaseAuthorityLost`
+        with the original reason when execution cannot continue.
         """
         body: dict[str, Any] = {
             "activity_attempt_id": activity_attempt_id,

{durable_workflow-2.7.0 → durable_workflow-2.8.0}/src/durable_workflow/errors.py

@@ -36,6 +36,15 @@ class QueryTaskAuthorityLost(DurableWorkflowError):
         self.reason = reason
 
 
+class ActivityLeaseAuthorityLost(DurableWorkflowError):
+    """An activity delivery lost its original live execution authority."""
+
+    def __init__(self, task_id: str, reason: str) -> None:
+        super().__init__(f"activity task {task_id!r} cannot continue: {reason}")
+        self.task_id = task_id
+        self.reason = reason
+
+
 class InvalidWorkflowDefinition(DurableWorkflowError, ValueError):
     """Workflow authoring uses an unsupported entry point or result."""