aws-durable-execution-sdk-python 2.1.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

aws_durable_execution_sdk_python/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Amazon.com, Inc. or its affiliates.
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "2.1.0"
+__version__ = "3.0.0"

aws_durable_execution_sdk_python/concurrency/executor.py

@@ -53,7 +53,6 @@ if TYPE_CHECKING:
     from collections.abc import Callable
     from aws_durable_execution_sdk_python.config import CompletionConfig
     from aws_durable_execution_sdk_python.context import DurableContext
-    from aws_durable_execution_sdk_python.lambda_service import OperationSubType
     from aws_durable_execution_sdk_python.serdes import SerDes
     from aws_durable_execution_sdk_python.state import (
         CheckpointedResult,
@@ -129,8 +128,8 @@ class ConcurrentExecutor(Generic[CallableType, ResultType]):
         executables: list[Executable[CallableType]],
         max_concurrency: int | None,
         completion_config: CompletionConfig,
-        sub_type_top: OperationSubType,
-        sub_type_iteration: OperationSubType,
+        sub_type_top: str,
+        sub_type_iteration: str,
         name_prefix: str,
         serdes: SerDes | None,
         operation_id_namespace: OperationIdNamespace,
@@ -702,7 +701,6 @@ class ConcurrentExecutor(Generic[CallableType, ResultType]):
             operation_identifier=operation_identifier,
             config=ChildConfig(
                 serdes=self.item_serdes or self.serdes,
-                sub_type=self.sub_type_iteration,
                 is_virtual=is_virtual,
             ),
         )

aws_durable_execution_sdk_python/concurrency/models.py

@@ -7,7 +7,7 @@ import logging
 from collections import Counter
 from dataclasses import dataclass
 from enum import Enum
-from typing import TYPE_CHECKING, Generic, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
 
 from aws_durable_execution_sdk_python.exceptions import (
     ChildContextError,
@@ -396,6 +396,12 @@ def envelope_summary_generator(
 
 @dataclass(frozen=True)
 class BatchItem(Generic[R]):
+    """One branch of a map or parallel batch.
+
+    ``error`` may be None on a FAILED item when its source contained no
+    ErrorObject. ``BatchResult.throw_if_error`` still raises for it.
+    """
+
     index: int
     status: BatchItemStatus
     result: R | None = None
@@ -489,18 +495,10 @@ class BatchResult(Generic[R], BatchResultProtocol[R]):  # noqa: PYI059
         }
 
     def succeeded(self) -> list[BatchItem[R]]:
-        return [
-            item
-            for item in self.all
-            if item.status is BatchItemStatus.SUCCEEDED and item.result is not None
-        ]
+        return [item for item in self.all if item.status is BatchItemStatus.SUCCEEDED]
 
     def failed(self) -> list[BatchItem[R]]:
-        return [
-            item
-            for item in self.all
-            if item.status is BatchItemStatus.FAILED and item.error is not None
-        ]
+        return [item for item in self.all if item.status is BatchItemStatus.FAILED]
 
     def started(self) -> list[BatchItem[R]]:
         return [item for item in self.all if item.status is BatchItemStatus.STARTED]
@@ -518,32 +516,44 @@ class BatchResult(Generic[R], BatchResultProtocol[R]):  # noqa: PYI059
         return any(item.status is BatchItemStatus.FAILED for item in self.all)
 
     def throw_if_error(self) -> None:
-        first_error = next(
-            (item.error for item in self.all if item.status is BatchItemStatus.FAILED),
+        first_failed = next(
+            (item for item in self.all if item.status is BatchItemStatus.FAILED),
             None,
         )
-        if first_error is not None:
+        if first_failed is not None:
+            first_error = first_failed.error
+            if first_error is None:
+                raise ChildContextError(
+                    message=(
+                        f"Batch item {first_failed.index} failed "
+                        "without an ErrorObject."
+                    )
+                )
+
             # Each item runs in a child context, so a failed item surfaces as a
             # ChildContextError wrapping the escaping error (reconstructed as its
             # typed form where possible, with __cause__ set). Remaining errors
             # stay in get_errors().
             first_error.raise_as_operation_error(ChildContextError)
         if self.completion_reason is CompletionReason.CUSTOM_COMPLETION_FAILED:
-            # A custom decision marked the batch failed with no item error.
+            # A custom decision marked the batch failed with no failed item.
             raise BatchCompletionError(self.completion_reason)
 
     def get_results(self) -> list[R]:
+        # None is a valid result for a branch that returns nothing.
         return [
-            item.result
+            cast(R, item.result)
             for item in self.all
-            if item.status is BatchItemStatus.SUCCEEDED and item.result is not None
+            if item.status is BatchItemStatus.SUCCEEDED
         ]
 
-    def get_errors(self) -> list[ErrorObject]:
+    def get_errors(self) -> list[ErrorObject | None]:
+        """Return one entry per FAILED item, in branch order.
+
+        An entry is None when the corresponding item has no ErrorObject.
+        """
         return [
-            item.error
-            for item in self.all
-            if item.status is BatchItemStatus.FAILED and item.error is not None
+            item.error for item in self.all if item.status is BatchItemStatus.FAILED
         ]
 
     @property

aws_durable_execution_sdk_python/config.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import math
 import random
+import string
 from dataclasses import dataclass, field
 from enum import Enum, StrEnum
 from typing import TYPE_CHECKING, Generic, TypeVar
@@ -18,7 +19,6 @@ T = TypeVar("T")
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from aws_durable_execution_sdk_python.lambda_service import OperationSubType
     from aws_durable_execution_sdk_python.retries import RetryDecision
     from aws_durable_execution_sdk_python.serdes import SerDes
     from aws_durable_execution_sdk_python.types import SummaryGenerator
@@ -481,13 +481,69 @@ class StepSemantics(Enum):
     AT_LEAST_ONCE_PER_RETRY = "AT_LEAST_ONCE_PER_RETRY"
 
 
+_SUB_TYPE_CHARACTERS = frozenset(string.ascii_letters + string.digits + "-_")
+_SUB_TYPE_MAX_LENGTH = 32
+
+
+def _validate_sub_type(sub_type: str | None) -> None:
+    """Raise ValidationError when sub_type is set and the service would reject it.
+
+    The service accepts 1 to 32 characters from A-Z, a-z, 0-9, hyphen, and
+    underscore. None and "" select the SDK default, so both are accepted.
+    Checking here raises before any checkpoint is sent, so a step body never
+    runs under a subtype the service will reject.
+    """
+    if not sub_type:
+        return
+    if (
+        len(sub_type) > _SUB_TYPE_MAX_LENGTH
+        or not set(sub_type) <= _SUB_TYPE_CHARACTERS
+    ):
+        msg = (
+            f"sub_type must be 1 to {_SUB_TYPE_MAX_LENGTH} characters from "
+            f"A-Z, a-z, 0-9, hyphen, and underscore, got: {sub_type!r}"
+        )
+        raise ValidationError(msg)
+
+
 @dataclass(frozen=True)
 class StepConfig:
-    """Configuration for a step."""
+    """Configuration for a step.
+
+    Args:
+        retry_strategy: Decides whether and when a failed attempt is retried.
+            If None, the SDK uses its default retry strategy.
+
+        step_semantics: How often one attempt may run the function.
+            AT_LEAST_ONCE_PER_RETRY (the default) checkpoints START without
+            waiting, so an interrupted attempt runs again on the next
+            invocation. AT_MOST_ONCE_PER_RETRY waits for the START checkpoint
+            first, and an interrupted attempt fails with StepInterruptedError
+            and goes to the retry strategy instead of running again.
+
+        serdes: Custom serialization/deserialization for the step result.
+            If None, uses the default JSON serializer.
+
+        sub_type: Subtype recorded in the checkpoint, in replay validation, and
+            in plugin events. The default is "Step".
+            A custom operation built from steps uses this to label its steps,
+            so history and plugins can filter them without parsing names.
+            The value must be 1 to 32 characters from A-Z, a-z, 0-9, hyphen,
+            and underscore; the config raises ValidationError otherwise. None
+            or an empty string selects the default. Do not reuse an
+            ``OperationSubType`` value: those label the SDK's own operations.
+            Replay compares the subtype with the checkpoint. So changing the
+            subtype of an existing step is a breaking change for executions
+            in flight.
+    """
 
     retry_strategy: Callable[[Exception, int], RetryDecision] | None = None
     step_semantics: StepSemantics = StepSemantics.AT_LEAST_ONCE_PER_RETRY
     serdes: SerDes | None = None
+    sub_type: str | None = field(default=None, kw_only=True)
+
+    def __post_init__(self) -> None:
+        _validate_sub_type(self.sub_type)
 
 
 @dataclass(frozen=True)
@@ -502,9 +558,18 @@ class ChildConfig(Generic[T]):
             Applied at the handler level to serialize the entire BatchResult object.
             If None, uses the default JSON serializer for BatchResult.
 
-        sub_type: Operation subtype identifier used for tracking and debugging.
-            Examples: OperationSubType.MAP_ITERATION, OperationSubType.PARALLEL_BRANCH.
-            Used internally by the execution engine for operation classification.
+        sub_type: Subtype recorded in the checkpoint, in replay validation, and
+            in plugin events. The default is "RunInChildContext".
+            A custom operation built from several durable operations uses this
+            to label its child context, so history and plugins can filter it
+            without parsing names. The value must be 1 to 32 characters from
+            A-Z, a-z, 0-9, hyphen, and underscore; the config raises
+            ValidationError otherwise. None or an empty string selects the
+            default. Do not reuse an ``OperationSubType`` value: those label
+            the SDK's own operations.
+            Replay compares the subtype with the checkpoint. So changing the
+            subtype of an existing child context is a breaking change for
+            executions in flight.
 
         summary_generator: Function generating the checkpoint payload for large
             results (>256KB). When the serialized result exceeds CHECKPOINT_SIZE_LIMIT,
@@ -528,10 +593,13 @@ class ChildConfig(Generic[T]):
     """
 
     serdes: SerDes | None = None
-    sub_type: OperationSubType | None = None
+    sub_type: str | None = None
     summary_generator: SummaryGenerator | None = None
     is_virtual: bool = False
 
+    def __post_init__(self) -> None:
+        _validate_sub_type(self.sub_type)
+
 
 @dataclass(frozen=True)
 class MapConfig(Generic[T]):
@@ -649,11 +717,45 @@ class InvokeConfig(Generic[P, R]):
 
 @dataclass(frozen=True)
 class CallbackConfig:
-    """Configuration for callbacks."""
+    """Configuration for callbacks.
+
+    Args:
+        timeout: Maximum time to wait for the callback result. The default,
+            a zero Duration, means no timeout.
+
+        heartbeat_timeout: Maximum time between heartbeats before the callback
+            fails. The default, a zero Duration, means no heartbeat timeout.
+
+        serdes: Custom deserialization for the callback result.
+            If None, the payload is returned as is, without JSON parsing.
+
+        sub_type: Subtype recorded in the checkpoint, in replay validation, and
+            in plugin events. The default is "Callback".
+            A custom operation built from callbacks uses this to label its
+            callbacks, so history and plugins can filter them without parsing
+            names. The value must be 1 to 32 characters from A-Z, a-z, 0-9,
+            hyphen, and underscore; the config raises ValidationError
+            otherwise. None or an empty string selects the default. Do not
+            reuse an ``OperationSubType`` value: those label the SDK's own
+            operations. Under
+            ``wait_for_callback`` the subtype labels the callback the
+            operation creates; the surrounding context keeps the subtype
+            "WaitForCallback".
+            Replay compares the subtype with the checkpoint. So changing the
+            subtype of an existing callback is a breaking change for
+            executions in flight.
+    """
 
     timeout: Duration = field(default_factory=Duration)
     heartbeat_timeout: Duration = field(default_factory=Duration)
     serdes: SerDes | None = None
+    # Keyword-only, so the positional order of every config, including
+    # WaitForCallbackConfig(timeout, heartbeat_timeout, serdes, retry_strategy),
+    # is unchanged from 2.x.
+    sub_type: str | None = field(default=None, kw_only=True)
+
+    def __post_init__(self) -> None:
+        _validate_sub_type(self.sub_type)
 
     @property
     def timeout_seconds(self) -> int:

aws_durable_execution_sdk_python/context.py

@@ -509,8 +509,15 @@ class DurableContext(DurableContextProtocol):
         )
 
     def _peek_next_checkpoint(self) -> CheckpointedResult:
-        """Return the checkpoint for this context's next operation, without consuming it."""
-        return self.state.get_checkpoint_result(self._peek_next_operation_id())
+        """Return the checkpoint for this context's next operation, without consuming it.
+
+        The read takes no plugin end hook: the hook of an operation a
+        checkpoint response completed during this invocation belongs to the
+        read that consumes the result, the operation's own.
+        """
+        return self.state.get_checkpoint_result(
+            self._peek_next_operation_id(), claim_end_hook=False
+        )
 
     def _next_operation_exists(self) -> bool:
         """True if a checkpoint exists for this context's next operation."""
@@ -548,9 +555,14 @@ class DurableContext(DurableContextProtocol):
         # Only look up a checkpoint when replaying. Operation call sites pass
         # their atomically allocated identifier so concurrent callers inspect
         # the checkpoint for their own ID rather than peeking at shared state.
+        # Both reads inspect: neither consumes the result, so neither takes
+        # the plugin end hook a checkpoint response may have recorded for the
+        # operation. The operation's own read, which consumes the result, does.
         next_checkpoint: CheckpointedResult | None = (
             (
-                self.state.get_checkpoint_result(operation_identifier.operation_id)
+                self.state.get_checkpoint_result(
+                    operation_identifier.operation_id, claim_end_hook=False
+                )
                 if operation_identifier is not None
                 else self._peek_next_checkpoint()
             )
@@ -610,7 +622,7 @@ class DurableContext(DurableContextProtocol):
     @contextmanager
     def _operation_replay_aware(
         self,
-        sub_type: OperationSubType,
+        sub_type: str,
         name: str | None = None,
         *,
         operation_type: OperationType,
@@ -644,14 +656,16 @@ class DurableContext(DurableContextProtocol):
         Args:
             name (str): Optional name for the operation.
             config (CallbackConfig): Configuration for the callback.
+                ``config.sub_type`` labels the operation; see CallbackConfig.
 
         Return:
-            Callback future. Use result() on this future to wait for the callback resuilt.
+            Callback future. Use result() on this future to wait for the callback result.
         """
         if not config:
             config = CallbackConfig()
+        sub_type = config.sub_type or OperationSubType.CALLBACK.value
         with self._operation_replay_aware(
-            OperationSubType.CALLBACK, name, operation_type=OperationType.CALLBACK
+            sub_type, name, operation_type=OperationType.CALLBACK
         ) as operation_identifier:
             executor: CallbackOperationExecutor = CallbackOperationExecutor(
                 state=self.state,
@@ -687,7 +701,7 @@ class DurableContext(DurableContextProtocol):
         if not config:
             config = InvokeConfig[P, R]()
         with self._operation_replay_aware(
-            OperationSubType.CHAINED_INVOKE,
+            OperationSubType.CHAINED_INVOKE.value,
             name,
             operation_type=OperationType.CHAINED_INVOKE,
         ) as operation_identifier:
@@ -717,7 +731,7 @@ class DurableContext(DurableContextProtocol):
             config.completion_config._validate_for_total(len(inputs))
 
         with self._operation_replay_aware(
-            OperationSubType.MAP, map_name, operation_type=OperationType.CONTEXT
+            OperationSubType.MAP.value, map_name, operation_type=OperationType.CONTEXT
         ) as operation_identifier:
             operation_id = operation_identifier.operation_id
             map_context = self.create_child_context(operation_id=operation_id)
@@ -742,7 +756,6 @@ class DurableContext(DurableContextProtocol):
                 state=self.state,
                 operation_identifier=operation_identifier,
                 config=ChildConfig(
-                    sub_type=OperationSubType.MAP,
                     serdes=config.serdes if config else None,
                     # The SDK-owned envelope records the completion decision for
                     # replay. A configured summary_generator only contributes the
@@ -768,7 +781,7 @@ class DurableContext(DurableContextProtocol):
             config.completion_config._validate_for_total(len(functions))
 
         with self._operation_replay_aware(
-            OperationSubType.PARALLEL, name, operation_type=OperationType.CONTEXT
+            OperationSubType.PARALLEL.value, name, operation_type=OperationType.CONTEXT
         ) as operation_identifier:
             operation_id = operation_identifier.operation_id
             parallel_context = self.create_child_context(operation_id=operation_id)
@@ -792,7 +805,6 @@ class DurableContext(DurableContextProtocol):
                 state=self.state,
                 operation_identifier=operation_identifier,
                 config=ChildConfig(
-                    sub_type=OperationSubType.PARALLEL,
                     serdes=config.serdes if config else None,
                     # The SDK-owned envelope records the completion decision for
                     # replay. A configured summary_generator only contributes the
@@ -815,19 +827,33 @@ class DurableContext(DurableContextProtocol):
         Use this to nest and group operations.
 
         Args:
-            callable (Callable[[DurableContext], T]): Run this callable and pass the child context as the argument to it.
+            func (Callable[[DurableContext], T]): Run this callable and pass the child context as the argument to it.
             name (str | None): name for the operation.
-            config (ChildConfig | None = None): c
+            config (ChildConfig | None = None): Configuration for the child
+                context. ``config.sub_type`` labels the operation; see
+                ChildConfig.
 
         Returns:
             T: The result of the callable.
         """
         step_name: str | None = self._resolve_step_name(name, func)
         sub_type = (
-            config.sub_type
-            if config and config.sub_type
-            else OperationSubType.RUN_IN_CHILD_CONTEXT
-        )
+            config.sub_type if config else None
+        ) or OperationSubType.RUN_IN_CHILD_CONTEXT.value
+        return self._run_in_child_context(func, step_name, config, sub_type)
+
+    def _run_in_child_context(
+        self,
+        func: Callable[[DurableContext], T],
+        step_name: str | None,
+        config: ChildConfig | None,
+        sub_type: str,
+    ) -> T:
+        """Run ``func`` in a child context that records ``sub_type``.
+
+        ``run_in_child_context`` resolves the caller's ``config.sub_type``
+        into ``sub_type``; ``wait_for_callback`` passes its own SDK subtype.
+        """
         is_virtual: bool = config.is_virtual if config else False
 
         with self._operation_replay_aware(
@@ -858,12 +884,24 @@ class DurableContext(DurableContextProtocol):
         name: str | None = None,
         config: StepConfig | None = None,
     ) -> T:
+        """Run a function once and checkpoint its result.
+
+        Args:
+            func (Callable[[StepContext], T]): The function to run.
+            name (str | None): Optional name for the operation.
+            config (StepConfig | None): Configuration for the step.
+                ``config.sub_type`` labels the operation; see StepConfig.
+
+        Returns:
+            T: The function's result, from the checkpoint on replay.
+        """
         step_name = self._resolve_step_name(name, func)
         logger.debug("Step name: %s", step_name)
         if not config:
             config = StepConfig()
+        sub_type = config.sub_type or OperationSubType.STEP.value
         with self._operation_replay_aware(
-            OperationSubType.STEP, step_name, operation_type=OperationType.STEP
+            sub_type, step_name, operation_type=OperationType.STEP
         ) as operation_identifier:
             executor: StepOperationExecutor[T] = StepOperationExecutor(
                 func=func,
@@ -886,7 +924,7 @@ class DurableContext(DurableContextProtocol):
             msg = "duration must be at least 1 second"
             raise ValidationError(msg)
         with self._operation_replay_aware(
-            OperationSubType.WAIT, name, operation_type=OperationType.WAIT
+            OperationSubType.WAIT.value, name, operation_type=OperationType.WAIT
         ) as operation_identifier:
             wait_seconds = duration.seconds
             executor: WaitOperationExecutor = WaitOperationExecutor(
@@ -912,10 +950,11 @@ class DurableContext(DurableContextProtocol):
         # inner failure on __cause__; translate to callback-typed errors here, at
         # the call site, so it re-fires identically on replay.
         try:
-            return self.run_in_child_context(
+            return self._run_in_child_context(
                 wait_in_child_context,
                 step_name,
-                ChildConfig(sub_type=OperationSubType.WAIT_FOR_CALLBACK),
+                None,
+                OperationSubType.WAIT_FOR_CALLBACK.value,
             )
         except ChildContextError as e:
             inner: BaseException | None = e.__cause__
@@ -956,7 +995,9 @@ class DurableContext(DurableContextProtocol):
             raise ValidationError(msg)
 
         with self._operation_replay_aware(
-            OperationSubType.WAIT_FOR_CONDITION, name, operation_type=OperationType.STEP
+            OperationSubType.WAIT_FOR_CONDITION.value,
+            name,
+            operation_type=OperationType.STEP,
         ) as operation_identifier:
             executor: WaitForConditionOperationExecutor[T] = (
                 WaitForConditionOperationExecutor(

aws_durable_execution_sdk_python/execution.py

@@ -28,7 +28,7 @@ from aws_durable_execution_sdk_python.lambda_service import (
     OperationUpdate,
 )
 from aws_durable_execution_sdk_python.plugin import (
-    DurableInstrumentationPlugin,
+    DurableInstrumentationPluginFactory,
     PluginExecutor,
 )
 from aws_durable_execution_sdk_python.plugin_discovery import (
@@ -170,7 +170,7 @@ def durable_execution(
     func: Callable[[Any, DurableContext], Any] | None = None,
     *,
     boto3_client: Boto3LambdaClient | None = None,
-    plugins: list[DurableInstrumentationPlugin] | None = None,
+    plugins: list[DurableInstrumentationPluginFactory] | None = None,
 ) -> Callable[[Any, LambdaContext], Any]:
     """
     Decorator to create a durable execution handler.
@@ -178,7 +178,10 @@ def durable_execution(
     Args:
         func: The user function to decorate
         boto3_client: Optional boto3 Lambda client to use
-        plugins: Optional list of instrumentation plugins to use
+        plugins: Optional list of instrumentation plugin factories. Each
+            factory's ``create_plugin`` is called once per invocation with that
+            invocation's ``InvocationStartInfo``, and the instance it returns
+            serves only that invocation.
     """
     # Decorator called with parameters
     if func is None:
@@ -190,9 +193,12 @@ def durable_execution(
     logger.debug("Starting durable execution handler...")
 
     configured_plugins = load_configured_plugins(plugins)
-    plugin_executor = PluginExecutor(configured_plugins)
 
+    @functools.wraps(func)
     def wrapper(event: Any, context: LambdaContext) -> MutableMapping[str, Any]:
+        # Only the factory list outlives an invocation. The worker below owns
+        # this fresh executor and all plugin lifecycle hooks.
+        plugin_executor = PluginExecutor(configured_plugins)
         invocation_input: DurableExecutionInvocationInput
         service_client: DurableServiceClient
 
@@ -487,10 +493,7 @@ def durable_execution(
                         # LIFO cleanup: branches join with checkpointing alive;
                         # then close stops checkpointing and the wait completes.
                         resources.callback(wait_for_checkpoint)
-                        resources.callback(
-                            plugin_executor._run_in_invocation_context,
-                            execution_state.close,
-                        )
+                        resources.callback(execution_state.close)
                         execution_operation = execution_state.get_execution_operation()
 
                         # execute the plugins
@@ -515,9 +518,7 @@ def durable_execution(
                         checkpoint_future = executor.submit(
                             execution_state.checkpoint_batches_forever
                         )
-                        output = plugin_executor._run_in_invocation_context(
-                            invoke_handler
-                        )
+                        output = invoke_handler()
                     # The ExitStack has now closed execution_state and joined the
                     # checkpoint thread. So any revocation observed while draining
                     # in-flight checkpoint work is visible here. A terminal status
@@ -539,17 +540,26 @@ def durable_execution(
                         output = (
                             DurableExecutionInvocationOutput.create_pending().to_dict()
                         )
-                    plugin_executor.on_invocation_end(
-                        DurableExecutionInvocationOutput.from_dict(output)
-                    )
-                    return output
-                except Exception as error:
-                    plugin_executor.on_invocation_end(
-                        DurableExecutionInvocationOutput.create_retry(
-                            ErrorObject.from_exception(error)
+                    completed = DurableExecutionInvocationOutput.from_dict(output)
+                except BaseException as error:
+                    # Every started plugin gets its End hook, including when
+                    # cancellation or a thread-control exception escapes. The
+                    # handler's original failure wins over an End-hook failure.
+                    try:
+                        plugin_executor.on_invocation_end(
+                            DurableExecutionInvocationOutput.create_retry(
+                                ErrorObject.from_exception(error)
+                            )
+                        )
+                    except BaseException:  # noqa: BLE001 - preserve the original failure
+                        logger.exception(
+                            "Plugin invocation-end hook failed while the invocation "
+                            "was already failing; the original failure is raised"
                         )
-                    )
                     raise
+                # End must run only once; its own failure is not a handler failure.
+                plugin_executor.on_invocation_end(completed)
+                return output
 
         with ThreadPoolExecutor(
             max_workers=2, thread_name_prefix="dex-handler"

aws_durable_execution_sdk_python/identifier.py

@@ -11,7 +11,6 @@ from aws_durable_execution_sdk_python.exceptions import (
 from aws_durable_execution_sdk_python.lambda_service import (
     Operation,
     OperationType,
-    OperationSubType,
 )
 
 
@@ -34,10 +33,15 @@ class OperationIdNamespace:
 
 @dataclass(frozen=True)
 class OperationIdentifier:
-    """Operation identity with an explicit type independent of its subtype."""
+    """Operation identity with an explicit type independent of its subtype.
+
+    ``sub_type`` is the subtype the operation records: the value of an
+    ``OperationSubType`` member for an SDK operation, or the caller-defined
+    string a step, a callback, or a child context was configured with.
+    """
 
     operation_id: str
-    sub_type: OperationSubType
+    sub_type: str
     parent_id: str | None = None
     name: str | None = None
     operation_type: OperationType = field(kw_only=True)
@@ -61,12 +65,9 @@ class OperationIdentifier:
             mismatches.append(
                 f"type checkpoint={checkpoint.operation_type.value!r} current={self.type.value!r}"
             )
-        if checkpoint.sub_type is not self.sub_type:
-            checkpoint_sub_type = (
-                checkpoint.sub_type.value if checkpoint.sub_type is not None else None
-            )
+        if checkpoint.sub_type != self.sub_type:
             mismatches.append(
-                f"subtype checkpoint={checkpoint_sub_type!r} current={self.sub_type.value!r}"
+                f"subtype checkpoint={checkpoint.sub_type!r} current={self.sub_type!r}"
             )
         if checkpoint_name != expected_name:
             mismatches.append(