dex-python-sdk 0.6.0__tar.gz → 0.8.0__tar.gz

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.6.0
+Version: 0.8.0
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -361,6 +361,17 @@ buffered sets and deletes. The matching `ChannelMap` methods are RPC-only,
 include buffered publishes, and omit empty instances. Keys are decoded and
 sorted. Use `force_complete_if_channels_empty(...)` for conditional completion.
 
+Request IDs are optional for both durable waits. When omitted, the server
+derives a namespaced stable ID from the Step execution or Attribute condition,
+such as `wait-for-attribute:myInt>10`. Reuse an override only for the same
+logical wait. The Client automatically reattaches transport long polls. If an
+earlier Update with that ID exhausted its handler budget, the server appends an
+increasing `-N` suffix and starts a new Update. `maximum_wait_time` is optional
+and is the total handler budget across reattachments; zero waits indefinitely.
+A positive budget expiry raises `WaitHandlerTimeoutError`. An abandoned infinite
+wait remains accepted and counts against Temporal's in-flight Update limit until
+it completes or the Flow closes.
+
 `Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
 `FlowResult` after hydrating every output-bearing completion. Use
 `single_output` only when the Flow contract produces exactly one output:
@@ -444,7 +455,10 @@ client operations, and assertions as the Java suite against an isolated
 The strongly typed contracts, registry, synchronous Client/Worker, optional
 `AsyncClient`/`AsyncWorker` (`grpc.aio`), and Rust-backed BlobCache are
 implemented. Python owns its gRPC transport; the native bridge is limited to
-the shared BlobCache. Design notes:
+the shared BlobCache. Serialized object values use wire encoding `json` for JSON
+and `raw` for raw bytes. Internal Blob references are opaque. Hydration sends the
+owning Flow ID with each reference, and the cache is isolated by
+`(flow_id, blob_ref)`. Design notes:
 [`python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md) and
 [`python-sdk-step-streaming.md`](../docs/design/plan/python-sdk-step-streaming.md).
 

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/README.md

@@ -345,6 +345,17 @@ buffered sets and deletes. The matching `ChannelMap` methods are RPC-only,
 include buffered publishes, and omit empty instances. Keys are decoded and
 sorted. Use `force_complete_if_channels_empty(...)` for conditional completion.
 
+Request IDs are optional for both durable waits. When omitted, the server
+derives a namespaced stable ID from the Step execution or Attribute condition,
+such as `wait-for-attribute:myInt>10`. Reuse an override only for the same
+logical wait. The Client automatically reattaches transport long polls. If an
+earlier Update with that ID exhausted its handler budget, the server appends an
+increasing `-N` suffix and starts a new Update. `maximum_wait_time` is optional
+and is the total handler budget across reattachments; zero waits indefinitely.
+A positive budget expiry raises `WaitHandlerTimeoutError`. An abandoned infinite
+wait remains accepted and counts against Temporal's in-flight Update limit until
+it completes or the Flow closes.
+
 `Client.wait_for_flow` and `AsyncClient.wait_for_flow` return a
 `FlowResult` after hydrating every output-bearing completion. Use
 `single_output` only when the Flow contract produces exactly one output:
@@ -428,7 +439,10 @@ client operations, and assertions as the Java suite against an isolated
 The strongly typed contracts, registry, synchronous Client/Worker, optional
 `AsyncClient`/`AsyncWorker` (`grpc.aio`), and Rust-backed BlobCache are
 implemented. Python owns its gRPC transport; the native bridge is limited to
-the shared BlobCache. Design notes:
+the shared BlobCache. Serialized object values use wire encoding `json` for JSON
+and `raw` for raw bytes. Internal Blob references are opaque. Hydration sends the
+owning Flow ID with each reference, and the cache is isolated by
+`(flow_id, blob_ref)`. Design notes:
 [`python-sdk-async-apis.md`](../docs/design/plan/python-sdk-async-apis.md) and
 [`python-sdk-step-streaming.md`](../docs/design/plan/python-sdk-step-streaming.md).
 

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/dex/__init__.py

@@ -62,10 +62,11 @@ from dex.flow_options import (
 )
 from dex.flow_result import FlowResult, StepCompletion
 from dex.runtime_errors import (
-    DexServiceError,
-    ErrorSubStatus,
     AttributeMapNotLoadedError,
+    ChannelMessageNotFoundError,
     ChannelMessagesNotLoadedError,
+    DexServiceError,
+    ErrorSubStatus,
     FlowAlreadyStartedError,
     FlowDefinitionError,
     FlowErrorType,
@@ -73,9 +74,9 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     InvalidStepResultError,
     LongPollTimeoutError,
-    ChannelMessageNotFoundError,
     RpcLockConflictError,
     ValueMappingError,
+    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
 from dex.step import (
@@ -108,6 +109,7 @@ from dex.stream import (
 from dex.subflow import SubFlow
 from dex.timer import Timer
 from dex.wait import Wait
+from dex.wait_options import WaitForAttributeOptions, WaitForStepCompletionOptions
 from dex.worker import Worker
 from dex.worker_options import WorkerOptions, WorkerTarget
 
@@ -164,6 +166,7 @@ __all__ = [
     "IndexType",
     "JsonCodec",
     "LongPollTimeoutError",
+    "WaitHandlerTimeoutError",
     "PersistenceSchema",
     "RPCResult",
     "RecoveryErrorInfo",
@@ -205,6 +208,8 @@ __all__ = [
     "WorkerInvocationError",
     "WorkerOptions",
     "WorkerTarget",
+    "WaitForAttributeOptions",
+    "WaitForStepCompletionOptions",
     "dead_end",
     "force_complete",
     "force_complete_if_channels_empty",

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/dex/_async_value_hydrator.py

@@ -20,6 +20,7 @@ _LOGGER = logging.getLogger(__name__)
 
 @dataclass
 class _PendingBlob:
+    flow_id: str
     blob_id: str
     is_object: bool
     request: pb.Value
@@ -36,21 +37,37 @@ class AsyncValueHydrator:
         self._service = service
         self._cache = cache
 
-    async def hydrate(self, value: pb.Value) -> pb.Value:
-        return (await self.hydrate_all([value]))[0]
+    async def hydrate(self, flow_id: str, value: pb.Value) -> pb.Value:
+        return (await self.hydrate_all(flow_id, [value]))[0]
 
-    async def hydrate_all(self, values: list[pb.Value]) -> list[pb.Value]:
+    async def hydrate_all(
+        self,
+        flow_id: str,
+        values: list[pb.Value],
+    ) -> list[pb.Value]:
+        return await self.hydrate_all_for_flows(
+            [(flow_id, value) for value in values]
+        )
+
+    async def hydrate_all_for_flows(
+        self,
+        flow_values: list[tuple[str, pb.Value]],
+    ) -> list[pb.Value]:
+        values = [value for _, value in flow_values]
         hydrated = list(values)
-        pending: dict[tuple[str, bool], _PendingBlob] = {}
-        for index, value in enumerate(values):
+        pending: dict[tuple[str, str, bool], _PendingBlob] = {}
+        for index, (flow_id, value) in enumerate(flow_values):
+            if not flow_id:
+                raise ValueError(f"Flow ID at index {index} is required")
             key = self._blob_key(value)
             if key is None:
                 self._validate_concrete(value)
                 continue
-            blob = pending.get(key)
+            flow_blob_key = (flow_id, key[0], key[1])
+            blob = pending.get(flow_blob_key)
             if blob is None:
-                blob = _PendingBlob(key[0], key[1], value)
-                pending[key] = blob
+                blob = _PendingBlob(flow_id, key[0], key[1], value)
+                pending[flow_blob_key] = blob
             blob.indexes.append(index)
 
         misses: list[_PendingBlob] = []
@@ -86,7 +103,7 @@ class AsyncValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = iter(await self.hydrate_all(values))
+        hydrated = iter(await self.hydrate_all(request.context.flow_id, values))
         result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
             result.context.last_heartbeat_value.CopyFrom(next(hydrated))
@@ -122,7 +139,11 @@ class AsyncValueHydrator:
         values.extend(message.value for message in channel_messages)
         for channel_result in request.condition_results.channel_results:
             values.extend(channel_result.values)
-        hydrated = iter(await self.hydrate_all(values))
+        for flow_result in request.condition_results.sub_flow_results:
+            values.extend(
+                completion.completed_step_output for completion in flow_result.results
+            )
+        hydrated = iter(await self.hydrate_all(request.context.flow_id, values))
         if has_step_input:
             result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
@@ -141,6 +162,9 @@ class AsyncValueHydrator:
         for channel_result in result.condition_results.channel_results:
             for value in channel_result.values:
                 value.CopyFrom(next(hydrated))
+        for flow_result in result.condition_results.sub_flow_results:
+            for completion in flow_result.results:
+                completion.completed_step_output.CopyFrom(next(hydrated))
         return result
 
     async def rpc_request(
@@ -156,7 +180,7 @@ class AsyncValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = await self.hydrate_all(values)
+        hydrated = await self.hydrate_all(request.context.flow_id, values)
         result.input.CopyFrom(hydrated[0])
         hydrated_entries = iter(hydrated[1:])
         for entry in result.attributes:
@@ -172,10 +196,11 @@ class AsyncValueHydrator:
 
     async def step_outputs(
         self,
+        flow_id: str,
         outputs: list[pb.StepCompletionOutput],
     ) -> list[pb.StepCompletionOutput]:
         values = [output.completed_step_output for output in outputs]
-        hydrated = await self.hydrate_all(values)
+        hydrated = await self.hydrate_all(flow_id, values)
         results: list[pb.StepCompletionOutput] = []
         for output, value in zip(outputs, hydrated):
             result = pb.StepCompletionOutput()
@@ -188,7 +213,15 @@ class AsyncValueHydrator:
         if not misses:
             return
         response = await self._service.LoadBlobs(
-            pb.LoadBlobsRequest(values=[miss.request for miss in misses])
+            pb.LoadBlobsRequest(
+                entries=[
+                    pb.LoadBlobRequestEntry(
+                        flow_id=miss.flow_id,
+                        blob_value=miss.request,
+                    )
+                    for miss in misses
+                ]
+            )
         )
         for miss in misses:
             concrete = response.values.get(miss.blob_id)
@@ -200,7 +233,7 @@ class AsyncValueHydrator:
 
     def _read_cache(self, blob: _PendingBlob) -> pb.Value | None:
         try:
-            payload = self._cache.get(blob.blob_id)
+            payload = self._cache.get(self._cache_key(blob))
             if payload is None:
                 return None
             if blob.is_object:
@@ -212,7 +245,7 @@ class AsyncValueHydrator:
         except Exception:
             _LOGGER.warning("cannot read cached blob %s", blob.blob_id, exc_info=True)
             try:
-                self._cache.delete(blob.blob_id)
+                self._cache.delete(self._cache_key(blob))
             except Exception:
                 _LOGGER.warning(
                     "cannot delete cached blob %s",
@@ -228,7 +261,7 @@ class AsyncValueHydrator:
                 if blob.is_object
                 else concrete.string_value.encode("utf-8")
             )
-            self._cache.put(blob.blob_id, payload)
+            self._cache.put(self._cache_key(blob), payload)
         except Exception:
             _LOGGER.warning("cannot cache blob %s", blob.blob_id, exc_info=True)
 
@@ -247,6 +280,10 @@ class AsyncValueHydrator:
             return blob_id, True
         return None
 
+    @staticmethod
+    def _cache_key(blob: _PendingBlob) -> str:
+        return f"{len(blob.flow_id)}:{blob.flow_id}{blob.blob_id}"
+
     @staticmethod
     def _validate_hydrated(blob: _PendingBlob, value: pb.Value) -> None:
         expected = "obj_value" if blob.is_object else "string_value"
@@ -268,7 +305,7 @@ class AsyncValueHydrator:
                 raise ValueError("non-finite numbers are unsupported")
             return
         if kind == "obj_value":
-            if value.obj_value.encoding not in ("json", "rawbytes"):
+            if value.obj_value.encoding not in ("json", "raw"):
                 raise ValueError(
                     f"unsupported object encoding {value.obj_value.encoding}"
                 )

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/dex/_grpc_errors.py

@@ -27,12 +27,17 @@ from dex.runtime_errors import (
     FlowNotFoundError,
     LongPollTimeoutError,
     RpcLockConflictError,
+    WaitHandlerTimeoutError,
     WorkerInvocationError,
 )
 
 FlowTargetRequirement = Literal["none", "existing", "active"]
 
-MAX_WORKER_STACK_TRACE_BYTES = 16 * 1024
+MAX_WORKER_ERROR_DETAIL_BYTES = 1024
+MAX_WORKER_ERROR_TYPE_BYTES = 256
+MAX_WORKER_STACK_TRACE_BYTES = 4 * 1024
+_ERROR_DETAIL_TRUNCATION_MARKER = b"\n... error detail truncated by Dex Python SDK ..."
+_ERROR_TYPE_TRUNCATION_MARKER = b"\n... error type truncated by Dex Python SDK ..."
 _STACK_TRACE_TRUNCATION_MARKER = b"\n... stack trace truncated by Dex Python SDK ..."
 
 
@@ -139,6 +144,8 @@ def translate_rpc_error(
         return LongPollTimeoutError(*parameters)
     if sub_status is ErrorSubStatus.CHANNEL_MESSAGE_NOT_FOUND:
         return ChannelMessageNotFoundError(*parameters)
+    if sub_status is ErrorSubStatus.WAIT_HANDLER_TIMEOUT:
+        return WaitHandlerTimeoutError(*parameters)
     return DexServiceError(*parameters)
 
 
@@ -179,11 +186,19 @@ def _worker_error_status(error: BaseException) -> status_pb2.Status:
         retry_after_error = error
         reported = error.cause
 
-    message = str(reported) or type(reported).__name__
+    message = _truncate_worker_failure_field(
+        str(reported) or type(reported).__name__,
+        MAX_WORKER_ERROR_DETAIL_BYTES,
+        _ERROR_DETAIL_TRUNCATION_MARKER,
+    )
     stack_trace_source = error if retry_after_error is not None else reported
     worker_error = pb.WorkerErrorResponse(
         detail=message,
-        error_type=f"{type(reported).__module__}.{type(reported).__qualname__}",
+        error_type=_truncate_worker_failure_field(
+            f"{type(reported).__module__}.{type(reported).__qualname__}",
+            MAX_WORKER_ERROR_TYPE_BYTES,
+            _ERROR_TYPE_TRUNCATION_MARKER,
+        ),
         stack_trace=_worker_stack_trace(stack_trace_source),
     )
     if retry_after_error is not None:
@@ -201,16 +216,25 @@ def _worker_stack_trace(error: BaseException) -> str:
     if error.__traceback__ is None:
         return ""
     lines = traceback.format_exception(type(error), error, error.__traceback__)
-    encoded = "".join(lines).encode()
-    if len(encoded) <= MAX_WORKER_STACK_TRACE_BYTES:
-        return encoded.decode()
-    prefix_length = MAX_WORKER_STACK_TRACE_BYTES - len(_STACK_TRACE_TRUNCATION_MARKER)
+    return _truncate_worker_failure_field(
+        "".join(lines),
+        MAX_WORKER_STACK_TRACE_BYTES,
+        _STACK_TRACE_TRUNCATION_MARKER,
+    )
+
+
+def _truncate_worker_failure_field(
+    value: str,
+    maximum_bytes: int,
+    truncation_marker: bytes,
+) -> str:
+    encoded = value.encode()
+    if len(encoded) <= maximum_bytes:
+        return value
+    prefix_length = maximum_bytes - len(truncation_marker)
     while prefix_length > 0 and (encoded[prefix_length] & 0xC0) == 0x80:
         prefix_length -= 1
-    return (
-        encoded[:prefix_length].decode(errors="replace")
-        + _STACK_TRACE_TRUNCATION_MARKER.decode()
-    )
+    return encoded[:prefix_length].decode() + truncation_marker.decode()
 
 
 def _map_sub_status(value: int) -> ErrorSubStatus:
@@ -225,5 +249,8 @@ def _map_sub_status(value: int) -> ErrorSubStatus:
         int(
             pb.ERROR_SUB_STATUS_CHANNEL_MESSAGE_NOT_FOUND
         ): ErrorSubStatus.CHANNEL_MESSAGE_NOT_FOUND,
+        int(
+            pb.ERROR_SUB_STATUS_WAIT_HANDLER_TIME_OUT
+        ): ErrorSubStatus.WAIT_HANDLER_TIMEOUT,
     }
     return statuses.get(value, ErrorSubStatus.UNCATEGORIZED)

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/dex/_value_hydrator.py

@@ -20,6 +20,7 @@ _LOGGER = logging.getLogger(__name__)
 
 @dataclass
 class _PendingBlob:
+    flow_id: str
     blob_id: str
     is_object: bool
     request: pb.Value
@@ -36,21 +37,31 @@ class ValueHydrator:
         self._service = service
         self._cache = cache
 
-    def hydrate(self, value: pb.Value) -> pb.Value:
-        return self.hydrate_all([value])[0]
+    def hydrate(self, flow_id: str, value: pb.Value) -> pb.Value:
+        return self.hydrate_all(flow_id, [value])[0]
 
-    def hydrate_all(self, values: list[pb.Value]) -> list[pb.Value]:
+    def hydrate_all(self, flow_id: str, values: list[pb.Value]) -> list[pb.Value]:
+        return self.hydrate_all_for_flows([(flow_id, value) for value in values])
+
+    def hydrate_all_for_flows(
+        self,
+        flow_values: list[tuple[str, pb.Value]],
+    ) -> list[pb.Value]:
+        values = [value for _, value in flow_values]
         hydrated = list(values)
-        pending: dict[tuple[str, bool], _PendingBlob] = {}
-        for index, value in enumerate(values):
+        pending: dict[tuple[str, str, bool], _PendingBlob] = {}
+        for index, (flow_id, value) in enumerate(flow_values):
+            if not flow_id:
+                raise ValueError(f"Flow ID at index {index} is required")
             key = self._blob_key(value)
             if key is None:
                 self._validate_concrete(value)
                 continue
-            blob = pending.get(key)
+            flow_blob_key = (flow_id, key[0], key[1])
+            blob = pending.get(flow_blob_key)
             if blob is None:
-                blob = _PendingBlob(key[0], key[1], value)
-                pending[key] = blob
+                blob = _PendingBlob(flow_id, key[0], key[1], value)
+                pending[flow_blob_key] = blob
             blob.indexes.append(index)
 
         misses: list[_PendingBlob] = []
@@ -86,7 +97,7 @@ class ValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = iter(self.hydrate_all(values))
+        hydrated = iter(self.hydrate_all(request.context.flow_id, values))
         result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
             result.context.last_heartbeat_value.CopyFrom(next(hydrated))
@@ -126,7 +137,7 @@ class ValueHydrator:
             values.extend(
                 completion.completed_step_output for completion in flow_result.results
             )
-        hydrated = iter(self.hydrate_all(values))
+        hydrated = iter(self.hydrate_all(request.context.flow_id, values))
         if has_step_input:
             result.step_input.CopyFrom(next(hydrated))
         if has_heartbeat:
@@ -163,7 +174,7 @@ class ValueHydrator:
             for message in channel_values.messages
         ]
         values.extend(message.value for message in channel_messages)
-        hydrated = self.hydrate_all(values)
+        hydrated = self.hydrate_all(request.context.flow_id, values)
         result.input.CopyFrom(hydrated[0])
         hydrated_entries = iter(hydrated[1:])
         for entry in result.attributes:
@@ -179,10 +190,11 @@ class ValueHydrator:
 
     def step_outputs(
         self,
+        flow_id: str,
         outputs: list[pb.StepCompletionOutput],
     ) -> list[pb.StepCompletionOutput]:
         values = [output.completed_step_output for output in outputs]
-        hydrated = self.hydrate_all(values)
+        hydrated = self.hydrate_all(flow_id, values)
         results: list[pb.StepCompletionOutput] = []
         for output, value in zip(outputs, hydrated):
             result = pb.StepCompletionOutput()
@@ -195,7 +207,15 @@ class ValueHydrator:
         if not misses:
             return
         response = self._service.LoadBlobs(
-            pb.LoadBlobsRequest(values=[miss.request for miss in misses])
+            pb.LoadBlobsRequest(
+                entries=[
+                    pb.LoadBlobRequestEntry(
+                        flow_id=miss.flow_id,
+                        blob_value=miss.request,
+                    )
+                    for miss in misses
+                ]
+            )
         )
         for miss in misses:
             concrete = response.values.get(miss.blob_id)
@@ -207,7 +227,7 @@ class ValueHydrator:
 
     def _read_cache(self, blob: _PendingBlob) -> pb.Value | None:
         try:
-            payload = self._cache.get(blob.blob_id)
+            payload = self._cache.get(self._cache_key(blob))
             if payload is None:
                 return None
             if blob.is_object:
@@ -219,7 +239,7 @@ class ValueHydrator:
         except Exception:
             _LOGGER.warning("cannot read cached blob %s", blob.blob_id, exc_info=True)
             try:
-                self._cache.delete(blob.blob_id)
+                self._cache.delete(self._cache_key(blob))
             except Exception:
                 _LOGGER.warning(
                     "cannot delete cached blob %s",
@@ -235,7 +255,7 @@ class ValueHydrator:
                 if blob.is_object
                 else concrete.string_value.encode("utf-8")
             )
-            self._cache.put(blob.blob_id, payload)
+            self._cache.put(self._cache_key(blob), payload)
         except Exception:
             _LOGGER.warning("cannot cache blob %s", blob.blob_id, exc_info=True)
 
@@ -254,6 +274,10 @@ class ValueHydrator:
             return blob_id, True
         return None
 
+    @staticmethod
+    def _cache_key(blob: _PendingBlob) -> str:
+        return f"{len(blob.flow_id)}:{blob.flow_id}{blob.blob_id}"
+
     @staticmethod
     def _validate_hydrated(blob: _PendingBlob, value: pb.Value) -> None:
         expected = "obj_value" if blob.is_object else "string_value"
@@ -275,7 +299,7 @@ class ValueHydrator:
                 raise ValueError("non-finite numbers are unsupported")
             return
         if kind == "obj_value":
-            if value.obj_value.encoding not in ("json", "rawbytes"):
+            if value.obj_value.encoding not in ("json", "raw"):
                 raise ValueError(
                     f"unsupported object encoding {value.obj_value.encoding}"
                 )

{dex_python_sdk-0.6.0 → dex_python_sdk-0.8.0}/dex/_value_mapper.py

@@ -22,7 +22,7 @@ from dex.dexpb import dex_pb2 as pb
 from dex.runtime_errors import ValueMappingError
 
 _JSON_ENCODING = "json"
-_RAW_BYTES_ENCODING = "rawbytes"
+_RAW_BYTES_ENCODING = "raw"
 
 
 class ValueMapper:
@@ -43,10 +43,7 @@ class ValueMapper:
     def _encode(self, value: Any, codec: Codec[Any]) -> pb.Value:
         if value is None:
             return pb.Value(
-                obj_value=pb.EncodedObject(
-                    encoding=_JSON_ENCODING,
-                    payload=b"null",
-                )
+                null_value=cast(struct_pb2.NullValue, struct_pb2.NULL_VALUE)
             )
         logical = codec.encode(value)
         if logical.kind is WireKind.STRING:
@@ -134,7 +131,7 @@ class ValueMapper:
         ):
             raise ValueError("blob-backed Value was not hydrated")
         if kind == "null_value":
-            raise ValueError("attribute deletion marker cannot be decoded")
+            return None
         raise TypeError(f"cannot decode {kind or 'empty Value'} as {codec.type_name}")
 
     def to_value(self, value: pb.Value) -> Value:
@@ -166,6 +163,8 @@ class ValueMapper:
             "internal_blob_id_for_obj_value",
         ):
             raise ValueError("blob-backed Value was not hydrated")
+        if kind == "null_value":
+            return Value(WireKind.JSON, "null")
         raise TypeError(f"cannot wrap {kind or 'empty Value'} as Value")
 
     @staticmethod