Document Avro JSON type boundaries

Author: durable-workflow-ops

README.md

@@ -184,6 +184,19 @@ quiet_client = Client(
 )
 ```
 
+## Avro payload type boundaries
+
+The default Avro codec uses a generic JSON wrapper so PHP, Python, and other
+workers can exchange the same wire format. It preserves JSON-native values:
+`None`, booleans, numbers, strings, lists, and dictionaries with string keys.
+
+Class-carrying values are not encoded with type metadata. Convert pydantic
+models, attrs classes, dataclasses, pendulum values, `datetime` / `date` /
+`time`, `UUID`, `Decimal`, and plain `Enum` values to explicit dictionaries or
+scalars before passing them to the SDK. `IntEnum` and `StrEnum` encode because
+they are JSON scalar subclasses, but they decode as `int` and `str`.
+`OrderedDict` decodes as a plain `dict`.
+
 ## Authentication
 
 For local servers that use one shared bearer token, pass `token=`:

src/durable_workflow/_avro.py

@@ -6,9 +6,20 @@
     base64( 0x00 || avro_binary( record{ json: string, version: int } ) )
 
 The ``json`` field carries ``json.dumps(value)``; ``version`` is currently
-``1``.  A ``0x01`` prefix is reserved for typed-schema payloads — those
-are not yet encodeable/decodeable from this SDK because typed schemas
-require a schema registry that is out of scope for the first Avro release.
+``1``. That means the generic wrapper preserves only JSON-native shapes:
+``None``, booleans, numbers, strings, lists, and mappings with string keys.
+Class identity is not carried on the wire. ``OrderedDict`` decodes as a plain
+``dict``; ``IntEnum`` decodes as ``int``; and ``StrEnum`` decodes as ``str``.
+Objects that the standard library JSON encoder does not know how to encode,
+including dataclasses, attrs classes, pydantic models, pendulum values,
+``datetime`` / ``date`` / ``time``, ``uuid.UUID``, ``decimal.Decimal``, and
+plain ``Enum`` values, raise ``TypeError`` during encode. Convert those values
+to explicit JSON-native dictionaries or scalars before passing them to the
+SDK, then rebuild domain objects in workflow or activity code.
+
+A ``0x01`` prefix is reserved for typed-schema payloads — those are not yet
+encodeable/decodeable from this SDK because typed schemas require a schema
+registry that is out of scope for the first Avro release.
 
 The ``avro`` third-party package is a core runtime dependency. If it is
 missing from a broken or partial installation, calling :func:`encode` or
@@ -49,6 +60,8 @@ def encode(value: Any) -> str:
     """Encode a Python value as an Avro generic-wrapper payload blob.
 
     Returns a base64 string the server accepts under ``payload_codec="avro"``.
+    The generic wrapper accepts the same value shapes as ``json.dumps``; adapt
+    domain objects to JSON-native data before encoding.
     """
     try:
         import avro.io

src/durable_workflow/serializer.py

@@ -10,6 +10,11 @@
   existing data only, not used for new workflows.
 - ``"avro"`` — the blob is a base64-encoded Avro generic-wrapper payload
   (see :mod:`durable_workflow._avro`). Default for all new v2 workflows.
+  The wrapper carries JSON-native values only. Class-carrying values such as
+  dataclasses, attrs classes, pydantic models, pendulum values, datetimes,
+  UUIDs, ``Decimal``, and plain ``Enum`` values need an explicit adapter to a
+  dictionary or scalar before encode; JSON-subclass values such as ``IntEnum``
+  and ``StrEnum`` round-trip as their JSON scalar, not as the original class.
 """
 from __future__ import annotations
 

tests/test_serializer.py

@@ -1,4 +1,10 @@
 import logging
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import date, datetime, time, timezone
+from decimal import Decimal
+from enum import Enum, IntEnum
+from uuid import UUID
 
 import pytest
 
@@ -16,6 +22,33 @@
     not _AVRO_AVAILABLE, reason="avro package not installed"
 )
 
+try:
+    from enum import StrEnum
+except ImportError:  # pragma: no cover - Python < 3.11 compatibility
+    StrEnum = None  # type: ignore[assignment,misc]
+
+
+@dataclass
+class SerializerDataclass:
+    name: str
+    count: int
+
+
+class SerializerEnum(Enum):
+    PENDING = "pending"
+
+
+class SerializerIntEnum(IntEnum):
+    LOW = 1
+
+
+if StrEnum is not None:
+
+    class SerializerStrEnum(StrEnum):
+        HIGH = "high"
+else:
+    SerializerStrEnum = None
+
 
 class TestEncode:
     def test_list(self) -> None:
@@ -170,6 +203,40 @@ def test_round_trip_containers(self) -> None:
             blob = serializer.encode(value, codec="avro")
             assert serializer.decode(blob, codec="avro") == value
 
+    @pytest.mark.parametrize(
+        "value",
+        [
+            SerializerDataclass(name="Ada", count=2),
+            datetime(2026, 4, 21, 10, 30, tzinfo=timezone.utc),
+            date(2026, 4, 21),
+            time(10, 30, tzinfo=timezone.utc),
+            UUID("12345678-1234-5678-1234-567812345678"),
+            Decimal("10.25"),
+            SerializerEnum.PENDING,
+        ],
+    )
+    def test_json_unsupported_user_types_fail_encode(self, value: object) -> None:
+        with pytest.raises(TypeError, match="not JSON serializable"):
+            serializer.encode(value, codec="avro")
+
+    def test_ordered_dict_decodes_as_plain_dict(self) -> None:
+        value = OrderedDict([("first", 1), ("second", 2)])
+        decoded = serializer.decode(serializer.encode(value, codec="avro"), codec="avro")
+        assert decoded == {"first": 1, "second": 2}
+        assert type(decoded) is dict
+
+    def test_int_enum_decodes_as_int(self) -> None:
+        decoded = serializer.decode(serializer.encode(SerializerIntEnum.LOW, codec="avro"), codec="avro")
+        assert decoded == 1
+        assert type(decoded) is int
+
+    @pytest.mark.skipif(StrEnum is None, reason="StrEnum requires Python 3.11+")
+    def test_str_enum_decodes_as_str(self) -> None:
+        assert SerializerStrEnum is not None
+        decoded = serializer.decode(serializer.encode(SerializerStrEnum.HIGH, codec="avro"), codec="avro")
+        assert decoded == "high"
+        assert type(decoded) is str
+
     @pytest.mark.parametrize(
         "name,blob,expected",
         [(name, blob, expected) for name, (blob, expected) in _PHP_AVRO_FIXTURES.items()],