dex-python-sdk 0.1.1__tar.gz → 0.1.3__tar.gz

{dex_python_sdk-0.1.1 → dex_python_sdk-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.1.1
+Version: 0.1.3
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -39,7 +39,7 @@ class Run(dex.Step[str]):
     def wait_for(
         self, context: dex.Context, input: str
     ) -> dex.Wait:
-        return dex.Wait.all_of(
+        return dex.Wait.until(
             dex.Timer.by_duration(timedelta(seconds=1))
         )
 
@@ -76,6 +76,11 @@ explicit codec only for a custom encoding or a type Registry cannot derive.
 `PersistenceSchema.of(...)` accepts attributes and channels together and
 partitions them by definition type.
 
+`Worker` and `AsyncWorker` synchronize all registered Indexed Attributes with
+Dex Server before opening their listener. Existing indexes return immediately;
+failure or the default two-minute deadline aborts startup. An indexed
+`AttributeMap` must provide one fixed `index_key`.
+
 Initial attributes retain their value types without a public wrapper class:
 
 ```python
@@ -86,6 +91,19 @@ options = (
 )
 ```
 
+Opt in when declaring an Attribute or AttributeMap, and select the Store in
+Flow configuration:
+
+```python
+email = dex.Attribute("customer-email", str, sync_to_attribute_store=True)
+config = dex.FlowConfig(attribute_store_name="profiles")
+```
+
+The Store is an asynchronous latest-state projection. Deletion writes SQL
+`NULL`, and projection failures do not roll back Flow Attributes. `None`
+preserves the current target; an explicit empty string disables future
+synchronization while retaining protocol presence.
+
 ```
 pip install dex-python-sdk==0.1.0
 ```
@@ -117,6 +135,45 @@ two handler calls. Timer and channel conditions determine how long a Step waits.
 codec before Client or Worker startup. `Client` methods use these typed objects
 instead of raw Flow, Step, or RPC strings.
 
+### Waiting and map inspection
+
+`Wait.all_of` and `Wait.any_of` may use unnamed Conditions. Every Condition in
+`Wait.any_combination_of` must have a non-empty user ID; the same Condition
+instance may appear in multiple combinations.
+
+Both `Client` and `AsyncClient` provide `wait_for_attribute_equal` and
+`wait_for_attribute_map_equal`. They target the current run and accept only
+string, bool, int, or float wire values. JSON objects, bytes, and null fail
+before transport. `AttributeMap.get_map_size/get_all_instance_keys` include
+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.
+
+### Errors
+
+Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
+(`get_attribute`, `describe_flow`, `wait_for_flow`, and `reset_flow`) raise
+`FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
+waits, config updates, and continue-as-new triggers raise
+`FlowNotActiveError` when no running Flow can accept the operation.
+
+```python
+try:
+    client.publish(flow_id, orders.approved, order_id)
+except dex.FlowNotActiveError:
+    # The Flow is missing or already closed.
+    pass
+```
+
+Duplicate starts, worker failures, RPC lock contention, and long-poll timeouts
+raise `FlowAlreadyStartedError`, `WorkerInvocationError`,
+`RpcLockConflictError`, and `LongPollTimeoutError`. All service errors retain
+`code`, `sub_status`, `detail`, `operation`, `flow_id`, and the original gRPC
+exception through Python exception chaining. Worker failures also expose
+`worker_code`, `worker_error_type`, and `worker_error_detail`. Registration,
+serialization, and invalid handler returns use `FlowDefinitionError`,
+`ValueMappingError`, and `InvalidStepResultError`.
+
 ### Sync vs asyncio
 
 - **Sync (default):** `Client` and `Worker` use blocking gRPC and a thread-pool
@@ -209,7 +266,18 @@ make -C ../protos proto-python
 Checked-in Python stubs land in `dex/dexpb/`.
 #### Linting
 
-To run linting for this project:
+Validate that every `dex.__all__` class, function, constant, public method,
+argument, return value, dataclass field, enum value, and public instance
+attribute has a Google-style docstring:
+
+```bash
+uv run --frozen python scripts/check_public_docs.py
+```
+
+The checker resolves definitions from the public package export table, so
+private helpers and generated protobuf modules are excluded. Use `help(dex.Client)`
+or IDE hover information to read the same documentation. To run all other
+linting for this project:
 
 ```bash
 uv run --frozen pre-commit run --show-diff-on-failure --color=always --all-files

{dex_python_sdk-0.1.1 → dex_python_sdk-0.1.3}/README.md

@@ -23,7 +23,7 @@ class Run(dex.Step[str]):
     def wait_for(
         self, context: dex.Context, input: str
     ) -> dex.Wait:
-        return dex.Wait.all_of(
+        return dex.Wait.until(
             dex.Timer.by_duration(timedelta(seconds=1))
         )
 
@@ -60,6 +60,11 @@ explicit codec only for a custom encoding or a type Registry cannot derive.
 `PersistenceSchema.of(...)` accepts attributes and channels together and
 partitions them by definition type.
 
+`Worker` and `AsyncWorker` synchronize all registered Indexed Attributes with
+Dex Server before opening their listener. Existing indexes return immediately;
+failure or the default two-minute deadline aborts startup. An indexed
+`AttributeMap` must provide one fixed `index_key`.
+
 Initial attributes retain their value types without a public wrapper class:
 
 ```python
@@ -70,6 +75,19 @@ options = (
 )
 ```
 
+Opt in when declaring an Attribute or AttributeMap, and select the Store in
+Flow configuration:
+
+```python
+email = dex.Attribute("customer-email", str, sync_to_attribute_store=True)
+config = dex.FlowConfig(attribute_store_name="profiles")
+```
+
+The Store is an asynchronous latest-state projection. Deletion writes SQL
+`NULL`, and projection failures do not roll back Flow Attributes. `None`
+preserves the current target; an explicit empty string disables future
+synchronization while retaining protocol presence.
+
 ```
 pip install dex-python-sdk==0.1.0
 ```
@@ -101,6 +119,45 @@ two handler calls. Timer and channel conditions determine how long a Step waits.
 codec before Client or Worker startup. `Client` methods use these typed objects
 instead of raw Flow, Step, or RPC strings.
 
+### Waiting and map inspection
+
+`Wait.all_of` and `Wait.any_of` may use unnamed Conditions. Every Condition in
+`Wait.any_combination_of` must have a non-empty user ID; the same Condition
+instance may appear in multiple combinations.
+
+Both `Client` and `AsyncClient` provide `wait_for_attribute_equal` and
+`wait_for_attribute_map_equal`. They target the current run and accept only
+string, bool, int, or float wire values. JSON objects, bytes, and null fail
+before transport. `AttributeMap.get_map_size/get_all_instance_keys` include
+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.
+
+### Errors
+
+Client calls raise concrete `DexServiceError` subclasses. Existing-Flow reads
+(`get_attribute`, `describe_flow`, `wait_for_flow`, and `reset_flow`) raise
+`FlowNotFoundError` when the Flow does not exist. Mutations, RPCs, timer/Step
+waits, config updates, and continue-as-new triggers raise
+`FlowNotActiveError` when no running Flow can accept the operation.
+
+```python
+try:
+    client.publish(flow_id, orders.approved, order_id)
+except dex.FlowNotActiveError:
+    # The Flow is missing or already closed.
+    pass
+```
+
+Duplicate starts, worker failures, RPC lock contention, and long-poll timeouts
+raise `FlowAlreadyStartedError`, `WorkerInvocationError`,
+`RpcLockConflictError`, and `LongPollTimeoutError`. All service errors retain
+`code`, `sub_status`, `detail`, `operation`, `flow_id`, and the original gRPC
+exception through Python exception chaining. Worker failures also expose
+`worker_code`, `worker_error_type`, and `worker_error_detail`. Registration,
+serialization, and invalid handler returns use `FlowDefinitionError`,
+`ValueMappingError`, and `InvalidStepResultError`.
+
 ### Sync vs asyncio
 
 - **Sync (default):** `Client` and `Worker` use blocking gRPC and a thread-pool
@@ -193,7 +250,18 @@ make -C ../protos proto-python
 Checked-in Python stubs land in `dex/dexpb/`.
 #### Linting
 
-To run linting for this project:
+Validate that every `dex.__all__` class, function, constant, public method,
+argument, return value, dataclass field, enum value, and public instance
+attribute has a Google-style docstring:
+
+```bash
+uv run --frozen python scripts/check_public_docs.py
+```
+
+The checker resolves definitions from the public package export table, so
+private helpers and generated protobuf modules are excluded. Use `help(dex.Client)`
+or IDE hover information to read the same documentation. To run all other
+linting for this project:
 
 ```bash
 uv run --frozen pre-commit run --show-diff-on-failure --color=always --all-files

{dex_python_sdk-0.1.1 → dex_python_sdk-0.1.3}/dex/__init__.py

@@ -53,11 +53,19 @@ from dex.flow_options import (
     StopType,
 )
 from dex.runtime_errors import (
-    DexException,
+    DexServiceError,
     ErrorSubStatus,
+    FlowAlreadyStartedError,
+    FlowDefinitionError,
     FlowErrorType,
+    FlowNotActiveError,
+    FlowNotFoundError,
     FlowUncompletedError,
+    InvalidStepResultError,
     LongPollTimeoutError,
+    RpcLockConflictError,
+    ValueMappingError,
+    WorkerInvocationError,
 )
 from dex.step import (
     RetryPolicy,
@@ -70,7 +78,7 @@ from dex.step import (
     WaitForFailurePolicy,
     dead_end,
     force_complete,
-    force_complete_when_channels_empty,
+    force_complete_if_channels_empty,
     force_fail,
     go_to,
     go_to_multi,
@@ -105,21 +113,27 @@ __all__ = [
     "CodecRegistry",
     "ConditionCombination",
     "Context",
-    "DexException",
+    "DexServiceError",
     "ErrorSubStatus",
     "Flow",
+    "FlowAlreadyStartedError",
     "FlowConfig",
+    "FlowDefinitionError",
     "FlowErrorType",
     "FlowInfo",
+    "FlowNotActiveError",
+    "FlowNotFoundError",
     "FlowStatus",
     "FlowUncompletedError",
     "HealthInfo",
     "IdReusePolicy",
+    "InvalidStepResultError",
     "IndexType",
     "JsonCodec",
     "LongPollTimeoutError",
     "PersistenceSchema",
     "RPCResult",
+    "RpcLockConflictError",
     "Registry",
     "ResetFlowOptions",
     "ResetType",
@@ -139,15 +153,17 @@ __all__ = [
     "Timer",
     "TimerId",
     "Value",
+    "ValueMappingError",
     "Wait",
     "WaitForFailurePolicy",
     "WireKind",
     "Worker",
+    "WorkerInvocationError",
     "WorkerOptions",
     "WorkerTarget",
     "dead_end",
     "force_complete",
-    "force_complete_when_channels_empty",
+    "force_complete_if_channels_empty",
     "force_fail",
     "graceful_complete",
     "go_to",

{dex_python_sdk-0.1.1 → dex_python_sdk-0.1.3}/dex/_async_worker_dispatcher.py

@@ -17,6 +17,7 @@ from dex._value_mapper import ValueMapper
 from dex._worker_dispatcher import WorkerDispatcher
 from dex.dexpb import dex_pb2 as pb
 from dex.flow import RPCResult, Registry
+from dex.runtime_errors import InvalidStepResultError, ValueMappingError
 from dex.step import StepDecision
 from dex.wait import Wait
 
@@ -30,13 +31,13 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
     ) -> None:
         self._registry = registry
         self._values = values
-        self._hydrator = hydrator  # type: ignore[assignment]
+        self._async_hydrator = hydrator
 
     async def invoke_wait_for(  # type: ignore[override]
         self,
         original: pb.InvokeWaitForMethodRequest,
     ) -> pb.InvokeWaitForMethodResponse:
-        request = await self._hydrator.wait_for_request(original)
+        request = await self._async_hydrator.wait_for_request(original)
         flow = self._registry._flow_by_type(request.flow_type)
         step = flow.step(request.step_type)
         context = InvocationContext(
@@ -50,24 +51,29 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
         wait = step.step.wait_for(context, input)
         if isawaitable(wait):
             wait = await wait
-        if not isinstance(wait, Wait):
-            raise TypeError("wait_for must return Wait")
-        response = pb.InvokeWaitForMethodResponse(
-            upsert_attributes=list(context.attribute_writes.values()),
-            upsert_step_exe_locals=list(context.local_writes.values()),
-            record_events=context.events,
-            publish_to_channel=context.publications,
-        )
-        waiting = self._map_wait(flow, wait)
-        if waiting is not None:
-            response.waiting_condition.CopyFrom(waiting)
-        return response
+        try:
+            if not isinstance(wait, Wait):
+                raise TypeError("wait_for must return Wait")
+            response = pb.InvokeWaitForMethodResponse(
+                upsert_attributes=list(context.attribute_writes.values()),
+                upsert_step_exe_locals=list(context.local_writes.values()),
+                record_events=context.events,
+                publish_to_channel=context.publications,
+            )
+            waiting = self._map_wait(flow, wait)
+            if waiting is not None:
+                response.waiting_condition.CopyFrom(waiting)
+            return response
+        except (TypeError, ValueError) as error:
+            raise InvalidStepResultError(
+                flow.name, step.name, "wait_for", str(error)
+            ) from error
 
     async def invoke_execute(  # type: ignore[override]
         self,
         original: pb.InvokeExecuteMethodRequest,
     ) -> pb.InvokeExecuteMethodResponse:
-        request = await self._hydrator.execute_request(original)
+        request = await self._async_hydrator.execute_request(original)
         flow = self._registry._flow_by_type(request.flow_type)
         step = flow.step(request.step_type)
         condition_results = (
@@ -86,21 +92,26 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
         decision: Any = step.step.execute(context, input)
         if isawaitable(decision):
             decision = await decision
-        if not isinstance(decision, StepDecision):
-            raise TypeError("execute must return StepDecision")
-        return pb.InvokeExecuteMethodResponse(
-            step_decision=self._map_decision(flow, decision),
-            upsert_attributes=list(context.attribute_writes.values()),
-            record_events=context.events,
-            upsert_step_exe_locals=list(context.local_writes.values()),
-            publish_to_channel=context.publications,
-        )
+        try:
+            if not isinstance(decision, StepDecision):
+                raise TypeError("execute must return StepDecision")
+            return pb.InvokeExecuteMethodResponse(
+                step_decision=self._map_decision(flow, decision),
+                upsert_attributes=list(context.attribute_writes.values()),
+                record_events=context.events,
+                upsert_step_exe_locals=list(context.local_writes.values()),
+                publish_to_channel=context.publications,
+            )
+        except (TypeError, ValueError) as error:
+            raise InvalidStepResultError(
+                flow.name, step.name, "execute", str(error)
+            ) from error
 
     async def invoke_rpc(  # type: ignore[override]
         self,
         original: pb.InvokeWorkerRPCRequest,
     ) -> pb.InvokeWorkerRPCResponse:
-        request = await self._hydrator.rpc_request(original)
+        request = await self._async_hydrator.rpc_request(original)
         flow = self._registry._flow_by_type(request.flow_type)
         rpc = flow.rpc(request.rpc_name)
         context = InvocationContext(
@@ -117,23 +128,28 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
         returned: Any = rpc.method(*arguments)
         if isawaitable(returned):
             returned = await returned
-        response = pb.InvokeWorkerRPCResponse(
-            upsert_attributes=list(context.attribute_writes.values()),
-            record_events=context.events,
-            publish_to_channel=context.publications,
-        )
-        if isinstance(returned, RPCResult):
-            if rpc.output_codec is None:
-                raise TypeError("RPCResult requires an output type")
-            response.output.CopyFrom(
-                self._values.encode(returned.output, rpc.output_codec)
+        try:
+            response = pb.InvokeWorkerRPCResponse(
+                upsert_attributes=list(context.attribute_writes.values()),
+                record_events=context.events,
+                publish_to_channel=context.publications,
             )
-            if returned.next_steps:
-                response.step_decision.next_steps.extend(
-                    self._map_movements(flow, returned.next_steps)
+            if isinstance(returned, RPCResult):
+                if rpc.output_codec is None:
+                    raise TypeError("RPCResult requires an output type")
+                response.output.CopyFrom(
+                    self._values.encode(returned.output, rpc.output_codec)
                 )
-        elif returned is None and rpc.output_codec is None:
-            response.output.CopyFrom(self._values.encode_dynamic(None))
-        else:
-            raise TypeError("RPC must return RPCResult or None")
-        return response
+                if returned.next_steps:
+                    response.step_decision.next_steps.extend(
+                        self._map_movements(flow, returned.next_steps)
+                    )
+            elif returned is None and rpc.output_codec is None:
+                response.output.CopyFrom(self._values.encode_dynamic(None))
+            else:
+                raise TypeError("RPC must return RPCResult or None")
+            return response
+        except ValueMappingError:
+            raise
+        except (TypeError, ValueError) as error:
+            raise InvalidStepResultError(flow.name, None, "rpc", str(error)) from error

dex_python_sdk-0.1.3/dex/_grpc_errors.py

@@ -0,0 +1,145 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Super Durable Source License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
+
+from __future__ import annotations
+
+from typing import Any, Literal, cast
+
+import grpc
+from google.protobuf import any_pb2
+from google.rpc import status_pb2
+from grpc_status import rpc_status
+
+from dex.dexpb import dex_pb2 as pb
+from dex.runtime_errors import (
+    DexServiceError,
+    ErrorSubStatus,
+    FlowAlreadyStartedError,
+    FlowNotActiveError,
+    FlowNotFoundError,
+    LongPollTimeoutError,
+    RpcLockConflictError,
+    WorkerInvocationError,
+)
+
+FlowTargetRequirement = Literal["none", "existing", "active"]
+
+
+def translate_rpc_error(
+    error: grpc.RpcError,
+    operation: str,
+    flow_id: str | None,
+    requirement: FlowTargetRequirement,
+) -> DexServiceError:
+    details: pb.ErrorResponse | None = None
+    try:
+        status = rpc_status.from_call(cast(grpc.Call, error))
+        if status is not None:
+            for packed in status.details:
+                candidate = pb.ErrorResponse()
+                if packed.Is(candidate.DESCRIPTOR):
+                    packed.Unpack(candidate)
+                    details = candidate
+                    break
+    except Exception as malformed:
+        translated = DexServiceError(
+            error.code(),
+            ErrorSubStatus.UNCATEGORIZED,
+            f"Dex returned malformed error details: {malformed}",
+            operation,
+            flow_id,
+        )
+        return translated
+    detail = (
+        details.detail if details is not None and details.detail else error.details()
+    ) or str(error)
+    code = error.code()
+    sub_status = (
+        _map_sub_status(details.sub_status)
+        if details is not None
+        else ErrorSubStatus.UNCATEGORIZED
+    )
+    parameters = (code, sub_status, detail, operation, flow_id)
+    if sub_status is ErrorSubStatus.FLOW_ALREADY_STARTED:
+        return FlowAlreadyStartedError(*parameters)
+    if sub_status is ErrorSubStatus.FLOW_NOT_EXISTS:
+        if requirement == "existing":
+            return FlowNotFoundError(*parameters)
+        if requirement == "active":
+            return FlowNotActiveError(*parameters)
+        return DexServiceError(*parameters)
+    if sub_status is ErrorSubStatus.WORKER_API_ERROR:
+        if code is grpc.StatusCode.ABORTED:
+            return RpcLockConflictError(*parameters)
+        return WorkerInvocationError(
+            *parameters,
+            _worker_code(details),
+            details.original_worker_error_type if details is not None else "",
+            details.original_worker_error_detail if details is not None else "",
+        )
+    if sub_status is ErrorSubStatus.LONG_POLL_TIMEOUT:
+        return LongPollTimeoutError(*parameters)
+    return DexServiceError(*parameters)
+
+
+def _worker_code(details: pb.ErrorResponse | None) -> grpc.StatusCode | None:
+    if details is None or details.original_worker_error_status == 0:
+        return None
+    return next(
+        (
+            code
+            for code in grpc.StatusCode
+            if code.value[0] == details.original_worker_error_status
+        ),
+        grpc.StatusCode.UNKNOWN,
+    )
+
+
+def abort_worker_error(
+    context: grpc.ServicerContext,
+    error: BaseException,
+) -> None:
+    context.abort_with_status(rpc_status.to_status(_worker_error_status(error)))
+
+
+async def async_abort_worker_error(
+    context: grpc.aio.ServicerContext[Any, Any],
+    error: BaseException,
+) -> None:
+    # types-grpcio on 3.11 omits aio abort_with_status; runtime provides it.
+    await cast(Any, context).abort_with_status(
+        rpc_status.to_status(_worker_error_status(error))
+    )
+
+
+def _worker_error_status(error: BaseException) -> status_pb2.Status:
+    message = str(error) or type(error).__name__
+    worker_error = pb.WorkerErrorResponse(
+        detail=message,
+        error_type=f"{type(error).__module__}.{type(error).__qualname__}",
+    )
+    packed = any_pb2.Any()
+    packed.Pack(worker_error)
+    return status_pb2.Status(
+        code=grpc.StatusCode.UNKNOWN.value[0],
+        message=message,
+        details=[packed],
+    )
+
+
+def _map_sub_status(value: int) -> ErrorSubStatus:
+    statuses: dict[int, ErrorSubStatus] = {
+        int(pb.ERROR_SUB_STATUS_UNCATEGORIZED): ErrorSubStatus.UNCATEGORIZED,
+        int(
+            pb.ERROR_SUB_STATUS_FLOW_ALREADY_STARTED
+        ): ErrorSubStatus.FLOW_ALREADY_STARTED,
+        int(pb.ERROR_SUB_STATUS_FLOW_NOT_EXISTS): ErrorSubStatus.FLOW_NOT_EXISTS,
+        int(pb.ERROR_SUB_STATUS_WORKER_API_ERROR): ErrorSubStatus.WORKER_API_ERROR,
+        int(pb.ERROR_SUB_STATUS_LONG_POLL_TIME_OUT): ErrorSubStatus.LONG_POLL_TIMEOUT,
+    }
+    return statuses.get(value, ErrorSubStatus.UNCATEGORIZED)

{dex_python_sdk-0.1.1 → dex_python_sdk-0.1.3}/dex/_invocation_context.py

@@ -10,10 +10,11 @@ from __future__ import annotations
 
 from enum import Enum
 from typing import Any, Sequence, TypeVar, cast
+from urllib.parse import unquote
 
 from dex._utils import require_name
 from dex._value_mapper import ValueMapper
-from dex.attribute import Attribute, AttributeMap
+from dex.attribute import Attribute, AttributeMap, _apply_attribute_store_sync
 from dex.channel import Channel, ChannelMap
 from dex.codec import Codec
 from dex.dexpb import dex_pb2 as pb
@@ -161,6 +162,7 @@ class InvocationContext:
         )
         if index is not None:
             write.index_config.CopyFrom(index)
+        _apply_attribute_store_sync(write, definition)
         self.attribute_writes[key] = write
 
     def _delete_attribute(
@@ -177,6 +179,7 @@ class InvocationContext:
         )
         if index is not None:
             write.index_config.CopyFrom(index)
+        _apply_attribute_store_sync(write, definition)
         self.attribute_writes[key] = write
 
     def _publish_channel(
@@ -202,6 +205,38 @@ class InvocationContext:
                 size=(current.size if current is not None else 0) + 1
             )
 
+    def _attribute_map_keys(
+        self,
+        definition: AttributeMap[object],
+    ) -> tuple[str, ...]:
+        self._require_registered(definition)
+        prefix = f"{definition.name}/"
+        physical_keys = {key for key in self._attributes if key.startswith(prefix)}
+        for key, write in self.attribute_writes.items():
+            if not key.startswith(prefix):
+                continue
+            if write.value.WhichOneof("kind") == "null_value":
+                physical_keys.discard(key)
+            else:
+                physical_keys.add(key)
+        return tuple(sorted(unquote(key[len(prefix) :]) for key in physical_keys))
+
+    def _channel_map_keys(
+        self,
+        definition: ChannelMap[object],
+    ) -> tuple[str, ...]:
+        self._require_registered(definition)
+        if self._method is not InvocationMethod.RPC:
+            raise ValueError("ChannelMap introspection requires an RPC invocation")
+        prefix = f"{definition.name}/"
+        return tuple(
+            sorted(
+                unquote(key[len(prefix) :])
+                for key, info in self._channel_infos.items()
+                if key.startswith(prefix) and info.size > 0
+            )
+        )
+
     def _channel_size(
         self,
         definition: Channel[object] | ChannelMap[object],