durable-workflow 2.13.2__tar.gz → 2.14.1__tar.gz

{durable_workflow-2.13.2/src/durable_workflow.egg-info → durable_workflow-2.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.13.2
+Version: 2.14.1
 Summary: Python client and worker SDK for Durable Workflow Cloud and self-hosted Server
 Author: Durable Workflow Contributors
 License-Expression: MIT

{durable_workflow-2.13.2 → durable_workflow-2.14.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.13.2"
+version = "2.14.1"
 description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -79,8 +79,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.13.2"
-registry-version = "2.13.2"
+product-train = "2.14.1"
+registry-version = "2.14.1"
 supported-server-versions = "2.8.0"
 supported-server-release-baselines = { "2" = "2.8.0", "3" = "3.0.0" }
 worker-protocol-version = "1.20"

{durable_workflow-2.13.2 → durable_workflow-2.14.1}/src/durable_workflow/__init__.py

@@ -98,6 +98,7 @@ from .errors import (
     ScheduleNotFound,
     ServerError,
     SignalFailed,
+    TypedValueError,
     Unauthorized,
     UpdateFailed,
     UpdateRejected,
@@ -280,6 +281,7 @@ __all__ = [
     "AuthCompositionContract",
     "AuthCompositionContractError",
     "NonRetryableError",
+    "TypedValueError",
     "ReplayOutcome",
     "Replayer",
     "Saga",

durable_workflow-2.14.1/src/durable_workflow/_condition_fingerprint.py

@@ -0,0 +1,229 @@
+"""Stable identity for ``wait_condition`` predicates (#258).
+
+The Server records the fingerprint a worker sends with ``open_condition_wait``
+and replay compares it, so the value must be the same on every Python version
+and in every process. Version 2 hashes the predicate's module, qualified name
+and a canonical form of its source AST. It never hashes bytecode, constant
+reprs, memory addresses, file paths or line numbers.
+
+Version 1 (every release through 2.14.0) hashed bytecode and ``repr`` of code
+constants, which change across Python versions and, for nested functions,
+across processes. Recorded v1 values cannot be recomputed portably, so replay
+treats a v1 value that differs from this process's v1 as unverifiable rather
+than as a changed predicate (see :func:`fingerprint_verdict`).
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import inspect
+import linecache
+import re
+from collections.abc import Callable
+from typing import Any, Literal
+
+V2_PREFIX = "dwpy2:sha256:"
+_LEGACY = re.compile(r"sha256:[0-9a-f]{64}\Z")
+# Fields that carry no predicate meaning or differ between Python versions.
+_SKIPPED_FIELDS = frozenset({"ctx", "kind", "type_comment", "type_params", "decorator_list", "returns"})
+_parsed: dict[tuple[str, int], ast.Module | None] = {}
+_nodes: dict[Any, str | None] = {}
+# Python 3.12 inlines list, dict and set comprehensions (PEP 709), which drops
+# their segment from a nested function's __qualname__.
+_INLINED_COMPREHENSION = re.compile(r"\.<(?:listcomp|dictcomp|setcomp)>")
+
+Verdict = Literal["match", "mismatch", "unverifiable"]
+
+
+def legacy_fingerprint(predicate: Callable[[], bool]) -> str:
+    """The v1 fingerprint, kept only to recognise histories recorded by 2.14.0 and earlier."""
+    h = hashlib.sha256()
+    h.update(b"durable-workflow-python.wait-condition.v1\0")
+    h.update(f"{getattr(predicate, '__module__', '')}\0".encode())
+    h.update(f"{getattr(predicate, '__qualname__', '')}\0".encode())
+    original = getattr(predicate, "__typed_workflow_method__", None)
+    code = getattr(original if original is not None else predicate, "__code__", None)
+    if code is None:
+        h.update(repr(predicate).encode())
+    else:
+        h.update(repr((
+            code.co_argcount, code.co_posonlyargcount, code.co_kwonlyargcount, code.co_code,
+            code.co_consts, code.co_names, code.co_varnames, code.co_freevars,
+        )).encode())
+    return f"sha256:{h.hexdigest()}"
+
+
+def is_legacy(value: Any) -> bool:
+    return isinstance(value, str) and _LEGACY.match(value) is not None
+
+
+def fingerprint(predicate: Callable[[], bool]) -> str | None:
+    """Return the v2 fingerprint, or None when the predicate's source is unavailable.
+
+    Without a fingerprint the wait is identified by its key and call order,
+    as in sdk-php.
+    """
+    function = _authored_function(predicate)
+    if function is None:
+        return None
+    code = function.__code__
+    if code not in _nodes:
+        _nodes[code] = _predicate_node(function)
+    node = _nodes[code]
+    if node is None:
+        return None
+    qualname = _INLINED_COMPREHENSION.sub("", getattr(function, "__qualname__", ""))
+    h = hashlib.sha256()
+    h.update(b"durable-workflow-python.wait-condition.v2\0")
+    h.update(f"{getattr(function, '__module__', '')}\0".encode())
+    h.update(f"{qualname}\0".encode())
+    h.update(node.encode())
+    return f"{V2_PREFIX}{h.hexdigest()}"
+
+
+def fingerprint_verdict(recorded: Any, authored: str | None, predicate: Callable[[], bool]) -> Verdict:
+    """Compare a recorded fingerprint with the authored predicate.
+
+    - No recorded value: nothing to compare.
+    - An identity supplied explicitly in another format (not v2, not None)
+      is compared exactly, as before.
+    - A v2 value is compared exactly; without source it cannot be checked.
+    - A v1 value equal to this process's v1 matches. Any other v1 value is
+      unverifiable, because v1 differs across Python versions and processes.
+    - Any other string is compared exactly, as before.
+    """
+    if not isinstance(recorded, str):
+        return "match"
+    if authored is not None and not authored.startswith(V2_PREFIX):
+        return "match" if recorded == authored else "mismatch"
+    if recorded.startswith(V2_PREFIX):
+        if authored is None:
+            return "unverifiable"
+        return "match" if recorded == authored else "mismatch"
+    if is_legacy(recorded):
+        return "match" if recorded == legacy_fingerprint(predicate) else "unverifiable"
+    return "match" if recorded == authored else "mismatch"
+
+
+def _authored_function(predicate: Any) -> Any:
+    target = getattr(predicate, "__typed_workflow_method__", None) or predicate
+    if inspect.ismethod(target):
+        target = target.__func__
+    target = getattr(target, "__typed_workflow_method__", None) or target
+    return target if inspect.isfunction(target) else None
+
+
+def _module_tree(function: Any) -> ast.Module | None:
+    try:
+        filename = inspect.getsourcefile(function) or inspect.getfile(function)
+    except (OSError, TypeError):
+        return None
+    lines = linecache.getlines(filename, function.__globals__)
+    if not lines:
+        return None
+    source = "".join(lines)
+    key = (filename, hash(source))
+    if key not in _parsed:
+        try:
+            _parsed[key] = ast.parse(source)
+        except (SyntaxError, ValueError):
+            _parsed[key] = None
+    return _parsed[key]
+
+
+def _predicate_node(function: Any) -> str | None:
+    tree = _module_tree(function)
+    if tree is None:
+        return None
+    code = function.__code__
+    first_line = code.co_firstlineno
+    if function.__name__ == "<lambda>":
+        lambdas = [node for node in ast.walk(tree) if isinstance(node, ast.Lambda) and node.lineno == first_line]
+        lambdas.sort(key=lambda node: node.col_offset)
+        # PEP 709 moves comprehension instructions into the enclosing lambda.
+        # Candidates indistinguishable before 3.12 can become distinct after
+        # inlining, so keep the combined AST on every version in this case.
+        has_inlined_comprehension = any(
+            isinstance(child, ast.ListComp | ast.DictComp | ast.SetComp)
+            for node in lambdas for child in ast.walk(node)
+        )
+        if len(lambdas) > 1 and not has_inlined_comprehension:
+            # Names and constants are stable across versions; bytecode only
+            # breaks a tie, and is compared within this interpreter.
+            matching = [node for node in lambdas if _compiles_to(node, code, compare_bytecode=False)]
+            if len(matching) > 1:
+                matching = [node for node in matching if _compiles_to(node, code, compare_bytecode=True)]
+            if len(matching) == 1:
+                lambdas = matching
+        if not lambdas:
+            return None
+        # Lambdas that start on the same line and compile identically share
+        # one fingerprint covering all of them.
+        return "|".join(_canonical(node) for node in lambdas)
+    definitions = [
+        node for node in ast.walk(tree)
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and node.name == function.__name__
+        and min([node.lineno, *(decorator.lineno for decorator in node.decorator_list)]) == first_line
+    ]
+    if len(definitions) != 1:
+        return None
+    return _canonical(definitions[0])
+
+
+def _compiles_to(node: ast.Lambda, code: Any, *, compare_bytecode: bool) -> bool:
+    """Whether *node* compiles to *code* on this interpreter.
+
+    The candidate is compiled inside a function that binds the live code's
+    free variables, so names resolve the same way. Only the choice of node
+    uses bytecode, which is valid within one interpreter; the fingerprint
+    hashes the node's AST, so it stays portable.
+    """
+    free = list(code.co_freevars)
+    lines = ["def __dw_outer__():"]
+    if free:
+        lines.append(f"    {' = '.join(free)} = None")
+    lines.append(f"    return ({ast.unparse(node)})")
+    try:
+        outer = compile("\n".join(lines), "<condition-fingerprint>", "exec")
+    except SyntaxError:
+        return False
+    function = next((const for const in outer.co_consts if hasattr(const, "co_code")), None)
+    candidate = next(
+        (const for const in getattr(function, "co_consts", ()) if getattr(const, "co_name", None) == "<lambda>"),
+        None,
+    )
+    return candidate is not None and (
+        (not compare_bytecode or candidate.co_code == code.co_code)
+        and candidate.co_argcount == code.co_argcount
+        and candidate.co_names == code.co_names
+        and candidate.co_varnames == code.co_varnames
+        and candidate.co_freevars == code.co_freevars
+        and _plain_constants(candidate) == _plain_constants(code)
+    )
+
+
+def _plain_constants(code: Any) -> list[Any]:
+    """Constants other than nested code and the qualnames Python 3.10 stores for them."""
+    return [
+        const for const in code.co_consts
+        if not hasattr(const, "co_code") and not (isinstance(const, str) and "<locals>" in const)
+    ]
+
+
+def _canonical(value: Any) -> str:
+    if isinstance(value, ast.AST):
+        parts = [type(value).__name__]
+        for name in value._fields:
+            if name in _SKIPPED_FIELDS:
+                continue
+            item = getattr(value, name, None)
+            if item is None or item == []:
+                continue
+            parts.append(f"{name}={_canonical(item)}")
+        return "(" + " ".join(parts) + ")"
+    if isinstance(value, list):
+        return "[" + ",".join(_canonical(item) for item in value) + "]"
+    if value is None or value is Ellipsis or isinstance(value, str | bytes | int | float | complex | bool):
+        return f"{type(value).__name__}:{value!r}"
+    return type(value).__name__

durable_workflow-2.14.1/src/durable_workflow/_typed_values.py

@@ -0,0 +1,311 @@
+"""Opt-in conversion between neutral payload values and annotated Python types.
+
+The wire format stays the neutral Avro Value: a dataclass travels as the
+string-keyed map of its fields and an ``Enum`` as its value, exactly as
+``dataclasses.asdict()`` and ``.value`` would produce by hand. Decoding is
+driven only by the receiver's own annotations, so no class name, tag or
+pickled object ever enters durable history.
+
+Decoding follows payload-evolution rules for rolling deploys: keys a target
+dataclass does not declare are ignored, and a missing field takes its
+default. A value that cannot be converted raises
+:class:`~durable_workflow.errors.TypedValueError`, which names the field path
+and the expected type but never the value.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import inspect
+import types
+from collections.abc import Callable
+from enum import Enum
+from typing import Any, Union, cast, get_args, get_origin, get_type_hints
+
+from .errors import TypedValueError
+
+_SCALARS: tuple[type, ...] = (str, int, float, bool, bytes)
+_PASS_THROUGH = (Any, object, inspect.Parameter.empty)
+
+
+def _type_name(annotation: Any) -> str:
+    """A short, module-free name for diagnostics, such as ``list[Item]``."""
+    if annotation is type(None) or annotation is None:
+        return "None"
+    if _is_union(annotation):
+        options = get_args(annotation)
+        concrete = [option for option in options if option is not type(None)]
+        if len(concrete) == 1 and len(options) == 2:
+            return f"Optional[{_type_name(concrete[0])}]"
+        return " | ".join(_type_name(option) for option in options)
+    origin = get_origin(annotation)
+    if origin is not None:
+        arguments = ", ".join(_type_name(argument) for argument in get_args(annotation))
+        name = getattr(origin, "__name__", repr(origin).replace("typing.", ""))
+        return f"{name}[{arguments}]" if arguments else name
+    if isinstance(annotation, type):
+        return annotation.__qualname__
+    return repr(annotation).replace("typing.", "")
+
+
+def _json_kind(value: Any) -> str:
+    """The neutral kind of a received value, never the value itself."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, bytes):
+        return "bytes"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _optional_member(annotation: Any) -> Any:
+    """Return T for Optional[T]; refuse every other union as ambiguous."""
+    options = get_args(annotation)
+    concrete = [option for option in options if option is not type(None)]
+    if len(concrete) != 1 or len(concrete) == len(options):
+        raise TypeError(
+            f"typed values support only Optional[T] unions; {_type_name(annotation)} is ambiguous"
+        )
+    return concrete[0]
+
+
+def _is_union(annotation: Any) -> bool:
+    return get_origin(annotation) in (Union, types.UnionType)
+
+
+def _dataclass_hints(cls: type) -> dict[str, Any]:
+    try:
+        return get_type_hints(cls)
+    except (NameError, TypeError) as error:
+        raise TypeError(f"typed values cannot resolve the annotations of {cls.__qualname__}: {error}") from None
+
+
+def validate_annotation(annotation: Any, where: str, _seen: frozenset[type] = frozenset()) -> None:
+    """Refuse an annotation this contract cannot decode unambiguously.
+
+    Called when a typed activity is declared or a ``result_type`` is given, so
+    an unsupported type fails at definition time instead of passing a plain
+    value through silently.
+    """
+    if annotation in _PASS_THROUGH or annotation is None or annotation is type(None):
+        return
+    if _is_union(annotation):
+        validate_annotation(_optional_member(annotation), where, _seen)
+        return
+    origin = get_origin(annotation)
+    if annotation is list or origin is list:
+        for item in get_args(annotation):
+            validate_annotation(item, where, _seen)
+        return
+    if annotation is dict or origin is dict:
+        arguments = get_args(annotation)
+        if arguments:
+            if arguments[0] is not str:
+                raise TypeError(f"{where}: typed maps need str keys, not {_type_name(arguments[0])}")
+            validate_annotation(arguments[1], where, _seen)
+        return
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        for member in annotation:
+            if not isinstance(member.value, str | int | float):
+                raise TypeError(
+                    f"{where}: {annotation.__qualname__} members must have str, int or float values"
+                )
+        return
+    if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
+        if annotation in _seen:
+            return
+        hints = _dataclass_hints(annotation)
+        for item in dataclasses.fields(annotation):
+            if item.init:
+                validate_annotation(hints.get(item.name, Any), f"{where}.{item.name}", _seen | {annotation})
+        return
+    if isinstance(annotation, type) and annotation in _SCALARS:
+        return
+    raise TypeError(f"{where}: typed values do not support {_type_name(annotation)}")
+
+
+def decode_payload_value(value: Any, annotation: Any, path: str = "value") -> Any:
+    """Decode an untrusted payload value; every refusal is a TypedValueError."""
+    try:
+        return from_payload_value(value, annotation, path)
+    except RecursionError:
+        raise TypedValueError(path, _type_name(annotation), "the value is nested too deeply") from None
+
+
+def from_payload_value(value: Any, annotation: Any, path: str = "value") -> Any:
+    """Return *value* converted to *annotation*, which must be validated."""
+    if annotation in _PASS_THROUGH:
+        return value
+    if annotation is None or annotation is type(None):
+        if value is not None:
+            raise TypedValueError(path, "None", f"got {_json_kind(value)}")
+        return None
+    if _is_union(annotation):
+        if value is None:
+            return None
+        return from_payload_value(value, _optional_member(annotation), path)
+    if value is None:
+        raise TypedValueError(path, _type_name(annotation), "got null")
+
+    origin = get_origin(annotation)
+    if annotation is list or origin is list:
+        if not isinstance(value, list):
+            raise TypedValueError(path, _type_name(annotation), f"got {_json_kind(value)}")
+        (item_type,) = get_args(annotation) or (Any,)
+        return [from_payload_value(item, item_type, f"{path}[{index}]") for index, item in enumerate(value)]
+
+    if annotation is dict or origin is dict:
+        if not isinstance(value, dict):
+            raise TypedValueError(path, _type_name(annotation), f"got {_json_kind(value)}")
+        _, item_type = get_args(annotation) or (str, Any)
+        # Map keys are user data (for example email addresses), so a path names
+        # an entry by its position, never by its key.
+        return {
+            key: from_payload_value(item, item_type, f"{path}[entry {index}]")
+            for index, (key, item) in enumerate(value.items())
+        }
+
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        return _enum_from_payload(value, annotation, path)
+
+    if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
+        return _dataclass_from_payload(value, annotation, path)
+
+    if annotation is float and isinstance(value, int) and not isinstance(value, bool):
+        return float(value)
+    if annotation is int and isinstance(value, bool):
+        raise TypedValueError(path, "int", "got boolean")
+    if isinstance(annotation, type) and annotation in _SCALARS:
+        if not isinstance(value, annotation):
+            raise TypedValueError(path, annotation.__qualname__, f"got {_json_kind(value)}")
+        return value
+    raise TypeError(f"{path}: typed values do not support {_type_name(annotation)}")
+
+
+def _enum_from_payload(value: Any, cls: type[Enum], path: str) -> Enum:
+    if isinstance(value, cls):
+        return value
+    for member in cls:
+        expected = member.value
+        same_kind = type(expected) is type(value) or (type(expected) is float and type(value) is int)
+        if same_kind and expected == value:
+            return member
+    # The diagnostic must not echo the received value.
+    raise TypedValueError(path, cls.__qualname__, f"the {_json_kind(value)} is not a member")
+
+
+def _dataclass_from_payload(value: Any, cls: type, path: str) -> Any:
+    if isinstance(value, cls):
+        return value
+    if not isinstance(value, dict):
+        raise TypedValueError(path, cls.__qualname__, f"got {_json_kind(value)}")
+    hints = _dataclass_hints(cls)
+    arguments: dict[str, Any] = {}
+    for item in dataclasses.fields(cls):
+        if not item.init:
+            # Computed fields are derived again by the dataclass itself.
+            continue
+        field_path = f"{path}.{item.name}"
+        annotation = hints.get(item.name, Any)
+        if item.name in value:
+            arguments[item.name] = from_payload_value(value[item.name], annotation, field_path)
+        elif item.default is dataclasses.MISSING and item.default_factory is dataclasses.MISSING:
+            raise TypedValueError(field_path, _type_name(annotation), "the field is missing")
+    # Keys the receiver does not declare are ignored for rolling deploys.
+    try:
+        return cls(**arguments)
+    except ValueError:
+        # A __post_init__ check refused the decoded fields. Its message can
+        # carry the values, so it is not repeated here.
+        raise TypedValueError(path, cls.__qualname__, "the dataclass refused the decoded fields") from None
+
+
+def to_payload_value(value: Any) -> Any:
+    """Return the neutral value for dataclass and ``Enum`` values, recursively.
+
+    Every other value is returned unchanged, so the codec keeps refusing what
+    it refuses today (for example datetimes and tuples). The result encodes
+    to the same bytes as ``dataclasses.asdict()`` with each ``Enum`` replaced
+    by its ``.value``.
+    """
+    if isinstance(value, Enum):
+        return to_payload_value(value.value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {item.name: to_payload_value(getattr(value, item.name)) for item in dataclasses.fields(value)}
+    if isinstance(value, list):
+        return [to_payload_value(item) for item in value]
+    if isinstance(value, dict):
+        return {key: to_payload_value(item) for key, item in value.items()}
+    return value
+
+
+def to_payload_values(values: list[Any]) -> list[Any]:
+    return [to_payload_value(value) for value in values]
+
+
+def typed_callable(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap *fn* so positional arguments decode to its annotations.
+
+    Annotations are validated here, so an unsupported type fails when the
+    activity is declared. The wrapper keeps *fn*'s module and qualified name:
+    the decorator binds that name to the wrapper, so supervised callbacks that
+    pickle by reference resolve to it.
+    """
+    signature = inspect.signature(fn)
+    try:
+        hints = get_type_hints(fn)
+    except (NameError, TypeError) as error:
+        raise TypeError(f"typed activity {fn.__qualname__} has unresolvable annotations: {error}") from None
+    positional: list[tuple[str, Any]] = []
+    variadic: tuple[str, Any] | None = None
+    for parameter in signature.parameters.values():
+        annotation = hints.get(parameter.name, Any)
+        if parameter.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+            validate_annotation(annotation, parameter.name)
+            positional.append((parameter.name, annotation))
+        elif parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            validate_annotation(annotation, parameter.name)
+            variadic = (parameter.name, annotation)
+
+    def convert(args: tuple[Any, ...]) -> list[Any]:
+        converted: list[Any] = []
+        for index, value in enumerate(args):
+            if index < len(positional):
+                name, annotation = positional[index]
+                converted.append(decode_payload_value(value, annotation, name))
+            elif variadic is not None:
+                name, annotation = variadic
+                converted.append(decode_payload_value(value, annotation, f"{name}[{index - len(positional)}]"))
+            else:
+                converted.append(value)
+        return converted
+
+    wrapper: Any
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def typed_async(*args: Any, **kwargs: Any) -> Any:
+            return to_payload_value(await fn(*convert(args), **kwargs))
+
+        wrapper = typed_async
+    else:
+
+        @functools.wraps(fn)
+        def typed_sync(*args: Any, **kwargs: Any) -> Any:
+            return to_payload_value(fn(*convert(args), **kwargs))
+
+        wrapper = typed_sync
+    wrapper.__typed_activity__ = fn
+    return cast(Callable[..., Any], wrapper)

{durable_workflow-2.13.2 → durable_workflow-2.14.1}/src/durable_workflow/activity.py

@@ -206,10 +206,25 @@ def _set_context(ctx: ActivityContext | None) -> contextvars.Token[ActivityConte
     return _current_context.set(ctx)
 
 
-def defn(*, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Register a callable as an activity type under a language-neutral name."""
+def defn(*, name: str, typed: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Register a callable as an activity type under a language-neutral name.
+
+    With ``typed=True``, positional arguments are decoded to the callable's
+    parameter annotations: dataclasses, ``Enum`` (including ``IntEnum`` and
+    ``StrEnum``), ``Optional[T]``, ``list[T]``, ``dict[str, T]`` and the
+    scalars ``str``, ``int``, ``float``, ``bool`` and ``bytes``. Keys a
+    dataclass does not declare are ignored and missing fields take their
+    defaults. A value that does not match fails the activity without retries
+    with :class:`~durable_workflow.errors.TypedValueError`. An annotation
+    outside this list raises ``TypeError`` here, when the activity is
+    declared. Untyped activities keep receiving plain values.
+    """
 
     def wrap(fn: Callable[..., Any]) -> Callable[..., Any]:
+        if typed:
+            from ._typed_values import typed_callable
+
+            fn = typed_callable(fn)
         fn.__activity_name__ = name  # type: ignore[attr-defined]
         _REGISTRY[name] = fn
         return fn

{durable_workflow-2.13.2 → durable_workflow-2.14.1}/src/durable_workflow/errors.py

@@ -881,6 +881,26 @@ class NonRetryableError(DurableWorkflowError):
         self.__cause__ = cause
 
 
+class TypedValueError(NonRetryableError, TypeError):
+    """A payload value does not match the receiver's declared type.
+
+    Raised by opt-in typed values: a ``typed=True`` activity's arguments, or an
+    activity result decoded to ``result_type``. ``path`` names the field (for
+    example ``order.items[2].sku``) and ``expected`` the declared type. The
+    message never contains the received value. An activity whose arguments do
+    not match fails without retries, because a retry cannot change the payload.
+    """
+
+    def __init__(self, path: str, expected: str, detail: str) -> None:
+        self.path = path
+        self.expected = expected
+        self.detail = detail
+        super().__init__(f"{path}: expected {expected}; {detail}")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (type(self), (self.path, self.expected, self.detail))
+
+
 class AvroNotInstalledError(DurableWorkflowError, ImportError):
     """Raised when the core ``avro`` runtime dependency is unavailable."""
 

{durable_workflow-2.13.2 → durable_workflow-2.14.1}/src/durable_workflow/worker.py

@@ -49,6 +49,7 @@ from ._failure_reporting import REQUEST_BYTES, exception_message, normalize_loca
 from ._prepared_local_activity import PreparedAttempt, PreparedCancellationObserved, PreparedLocalRunner
 from ._query_task_authority import QueryTaskAuthority, current_query_authority
 from ._sticky_workflow_cache import CacheKey, StickyWorkflowCache, complete_history
+from ._typed_values import to_payload_value
 from .activity import ActivityContext, ActivityInfo, _set_context
 from .auth_composition import (
     AUTH_COMPOSITION_CONTRACT_SCHEMA,
@@ -2505,6 +2506,9 @@ class Worker:
                     "duration_ms": max(0, round((time.monotonic() - attempt_started_at) * 1000)),
                     "heartbeats": heartbeats,
                 })
+                # The workflow receives the same neutral value on this first
+                # run as on replay of the recorded result.
+                result = to_payload_value(result)
                 try:
                     inline_result = serializer.envelope(result, codec=payload_codec)
                 except Exception:
@@ -3270,6 +3274,7 @@ class Worker:
         finally:
             _set_context(None)
 
+        result = to_payload_value(result)
         log.info("completing activity task %s (%s) -> %r", task_id, activity_type, result)
         try:
             await self.client.complete_activity_task(