memoflow-sdk 0.1.0__py3-none-any.whl

memoflow/__init__.py

@@ -0,0 +1,288 @@
+"""memoflow Python SDK — durable workflows with checkpoint/memoization.
+
+Explicit steps (P12.2): decorators + async context + WorkerSession-stream
+worker + WorkflowService client. Step identity is cross-SDK compatible with
+the TypeScript SDK by construction (Design Law 1; enforced by the protocol
+conformance kit at packages/protocol-kit).
+"""
+from ._codec import (
+    PAYLOAD_CODEC_VERSION,
+    PAYLOAD_CONTENT_TYPE,
+    PAYLOAD_ENVELOPE_VERSION,
+    PORTABLE_UNDEFINED,
+    PortableMap,
+    StepError,
+    decode_portable_payload,
+    deserialize_step_output,
+    encode_portable_payload,
+    is_portable_envelope,
+    parse_duration,
+    serialize_step_output,
+)
+from ._http_effect import idempotency_key_for
+from ._registry import activity, query, run, signal, workflow
+from ._step_key import NonDeterminismError, StepKeyTracker, step_key_hash
+from ._version import SDK_VERSION, __version__
+from .activity_context import (
+    ActivityContext,
+    ActivityExecutionIdentity,
+    CancelledError,
+    DurableOutputChunk,
+    ForkEffectBlockedError,
+    ForkExecutionOverride,
+    ForkExecutionPolicy,
+    LlmStepMeta,
+    RateLimitError,
+    activity_context,
+)
+from .ai import AiUsageAccumulator, AiUsageAggregationMode, NormalizedAiUsage
+from .ai_budget import (
+    AiBudgetDeniedError,
+    AiBudgetEstimate,
+    AiBudgetPriceIdentity,
+    AiBudgetReservationHandle,
+    AiBudgetReservationsUnsupportedError,
+)
+from .ai_budget_client import (
+    AiBudgetAccount,
+    AiBudgetClient,
+    AiBudgetLimit,
+    AiBudgetLimits,
+    AiBudgetPolicy,
+    AiBudgetReconciliation,
+    AiBudgetReconciliationPage,
+)
+from .ai_invocation import (
+    AiFinishReason,
+    AiInvocationHandle,
+    AiInvocationLedgerUnsupportedError,
+    AiOperation,
+    AiPayloadDescriptor,
+    AiPriceSnapshot,
+    AiProviderExtension,
+    AiRetryAndRateLimit,
+    AiToolDefinitions,
+    AiToolEffectHandle,
+    CompleteAiInvocation,
+    CompleteAiToolEffect,
+    StartAiInvocation,
+    StartAiToolEffect,
+)
+from .client import (
+    ResultTimeoutError,
+    WorkflowBlockedError,
+    WorkflowCancelledError,
+    WorkflowClient,
+    WorkflowFailedError,
+    WorkflowTimedOutError,
+)
+from .client_types import (
+    ApprovalActor,
+    ApprovalMutationResult,
+    ApprovalPolicy,
+    ApprovalWorkItem,
+    DescribeResult,
+    EvaluationScore,
+    ForkResult,
+    ListApprovalsResult,
+    ListDebouncesResult,
+    ListQueuesResult,
+    ListWorkersResult,
+    ListWorkflowEvaluationsResult,
+    ListWorkflowsResult,
+    NamespaceConfigResult,
+    OutputChunk,
+    ScheduleInfo,
+    StartDebouncedResult,
+    StartResult,
+    UpsertScheduleResult,
+    WorkflowEvaluation,
+    WorkflowEvaluationMutationResult,
+    WorkflowHistoryResult,
+    WorkflowInfo,
+)
+from .connection import ConnectionConfig, RpcCallOptions, TlsConfig
+from .context import SignalTimeoutError, WorkflowContext
+from .errors import (
+    PAYLOAD_DESERIALIZATION_ERROR,
+    PAYLOAD_SERIALIZATION_ERROR,
+    PROTOCOL_VALIDATION_ERROR,
+    MemoflowSdkError,
+    PayloadDeserializationError,
+    PayloadSerializationError,
+    ProtocolValidationError,
+    RemoteError,
+    RemoteErrorDetail,
+    RpcTransportError,
+    parse_remote_error_detail,
+    remote_error_from_grpc,
+)
+from .payload_codec import (
+    ENVELOPE_KEY,
+    UNVERSIONED,
+    CodecRegistry,
+    PayloadCodec,
+    PayloadVersionSkewError,
+    codecs,
+)
+from .retention_client import (
+    RetentionClient,
+    RetentionDeletionJob,
+    RetentionExpiryReconciliation,
+    RetentionHttpError,
+    RetentionLegalHold,
+    RetentionMutationResult,
+    RetentionPolicy,
+    RetentionReconciliationCandidate,
+    RetentionReconciliationPreview,
+    RetentionReconciliationResult,
+    RetentionScope,
+)
+from .telemetry import inject_current_context, with_provider_span
+from .transactional_step import (
+    AsyncPgQueryable,
+    StaleSqlContractError,
+    TransactionalStepConfig,
+    TransactionalStepUnsupportedError,
+    fingerprint_postgres_target,
+)
+from .worker import ReconnectConfig, SandboxAttestation, Worker, WorkerEvictedError
+
+__all__ = [
+    "SDK_VERSION",
+    "AiBudgetDeniedError",
+    "AiBudgetEstimate",
+    "AiBudgetPriceIdentity",
+    "AiBudgetReservationHandle",
+    "AiBudgetReservationsUnsupportedError",
+    "AiBudgetClient",
+    "AiBudgetReconciliation",
+    "AiBudgetReconciliationPage",
+    "AiBudgetAccount",
+    "AiBudgetLimit",
+    "AiBudgetLimits",
+    "AiBudgetPolicy",
+    "RetentionClient",
+    "RetentionDeletionJob",
+    "RetentionExpiryReconciliation",
+    "RetentionHttpError",
+    "RetentionLegalHold",
+    "RetentionMutationResult",
+    "RetentionPolicy",
+    "RetentionReconciliationCandidate",
+    "RetentionReconciliationPreview",
+    "RetentionReconciliationResult",
+    "RetentionScope",
+    "__version__",
+    "workflow",
+    "run",
+    "activity",
+    "signal",
+    "query",
+    "Worker",
+    "ReconnectConfig",
+    "WorkerEvictedError",
+    "WorkflowClient",
+    "ApprovalActor",
+    "ApprovalMutationResult",
+    "ApprovalPolicy",
+    "ApprovalWorkItem",
+    "EvaluationScore",
+    "ListApprovalsResult",
+    "WorkflowEvaluation",
+    "ListWorkflowEvaluationsResult",
+    "WorkflowEvaluationMutationResult",
+    "WorkflowContext",
+    "ConnectionConfig",
+    "RpcCallOptions",
+    "TlsConfig",
+    "StartResult",
+    "StartDebouncedResult",
+    "UpsertScheduleResult",
+    "ScheduleInfo",
+    "ForkResult",
+    "WorkflowInfo",
+    "ListWorkflowsResult",
+    "NamespaceConfigResult",
+    "ListWorkersResult",
+    "ListQueuesResult",
+    "ListDebouncesResult",
+    "DescribeResult",
+    "WorkflowHistoryResult",
+    "OutputChunk",
+    "ActivityContext",
+    "ActivityExecutionIdentity",
+    "DurableOutputChunk",
+    "ForkEffectBlockedError",
+    "ForkExecutionPolicy",
+    "ForkExecutionOverride",
+    "activity_context",
+    "CancelledError",
+    "RateLimitError",
+    "LlmStepMeta",
+    "AiUsageAccumulator",
+    "AiUsageAggregationMode",
+    "NormalizedAiUsage",
+    "AiOperation",
+    "AiFinishReason",
+    "AiPayloadDescriptor",
+    "AiPriceSnapshot",
+    "AiRetryAndRateLimit",
+    "AiProviderExtension",
+    "AiToolDefinitions",
+    "StartAiInvocation",
+    "CompleteAiInvocation",
+    "StartAiToolEffect",
+    "CompleteAiToolEffect",
+    "AiInvocationHandle",
+    "AiToolEffectHandle",
+    "AiInvocationLedgerUnsupportedError",
+    "AsyncPgQueryable",
+    "TransactionalStepConfig",
+    "SandboxAttestation",
+    "TransactionalStepUnsupportedError",
+    "StaleSqlContractError",
+    "fingerprint_postgres_target",
+    "inject_current_context",
+    "with_provider_span",
+    "NonDeterminismError",
+    "SignalTimeoutError",
+    "StepError",
+    "StepKeyTracker",
+    "step_key_hash",
+    "parse_duration",
+    "serialize_step_output",
+    "deserialize_step_output",
+    "PayloadCodec",
+    "CodecRegistry",
+    "PayloadVersionSkewError",
+    "ENVELOPE_KEY",
+    "UNVERSIONED",
+    "codecs",
+    "idempotency_key_for",
+    "PortableMap",
+    "PORTABLE_UNDEFINED",
+    "encode_portable_payload",
+    "decode_portable_payload",
+    "is_portable_envelope",
+    "PAYLOAD_ENVELOPE_VERSION",
+    "PAYLOAD_CODEC_VERSION",
+    "PAYLOAD_CONTENT_TYPE",
+    "WorkflowFailedError",
+    "WorkflowCancelledError",
+    "WorkflowTimedOutError",
+    "WorkflowBlockedError",
+    "ResultTimeoutError",
+    "MemoflowSdkError",
+    "PayloadSerializationError",
+    "PayloadDeserializationError",
+    "ProtocolValidationError",
+    "PAYLOAD_SERIALIZATION_ERROR",
+    "PAYLOAD_DESERIALIZATION_ERROR",
+    "PROTOCOL_VALIDATION_ERROR",
+    "RemoteError",
+    "RemoteErrorDetail",
+    "RpcTransportError",
+    "parse_remote_error_detail",
+    "remote_error_from_grpc",
+]

memoflow/_codec.py

@@ -0,0 +1,382 @@
+"""Portable payload envelope v1 and duration parsing.
+
+Payloads remain opaque bytes to the server. The tagged canonical body and
+deterministic protobuf envelope make normal TypeScript/Python values
+byte-compatible without JSON's silent type coercions. The older TypeScript
+``$mfv`` registered-codec wrapper may still be nested inside the portable
+body; Python intentionally does not hydrate application-specific TS codecs.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import math
+import re
+import struct
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from google.protobuf.message import DecodeError
+
+from .errors import (
+    MemoflowSdkError,
+    PayloadDeserializationError,
+    PayloadSerializationError,
+    ProtocolValidationError,
+)
+
+_DURATION_RE = re.compile(r"^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$")
+_UNIT_MS: dict[str, int] = {"ms": 1, "s": 1000, "m": 60_000, "h": 3_600_000, "d": 86_400_000}
+_MAX_PROTOBUF_DURATION_MS = 315_576_000_000_999
+_DURATION_FORMAT_REASON = 'must be a duration string like "5s", "1m", or "100ms"'
+_DURATION_VALUE_REASON = (
+    "must resolve to a positive whole number of milliseconds within the protobuf Duration range"
+)
+
+PAYLOAD_MAGIC = b"MFP1"
+PAYLOAD_ENVELOPE_VERSION = 1
+PAYLOAD_CODEC_NAME = "memoflow-portable-json"
+PAYLOAD_CODEC_VERSION = 1
+PAYLOAD_CONTENT_TYPE = "application/vnd.memoflow.portable-json.v1+json"
+MAX_PAYLOAD_BODY_BYTES = 16 * 1024 * 1024
+MAX_PAYLOAD_METADATA_BYTES = 16 * 1024
+MAX_PAYLOAD_METADATA_ENTRIES = 32
+MAX_LEGACY_JSON_DEPTH = 128
+_META_KEY_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+_ENVELOPE_PREFIX = b"\x0a\x04MFP1"
+_SAFE_INTEGER_MAX = 9_007_199_254_740_991
+
+
+@dataclass(frozen=True)
+class PortableMap:
+    entries: tuple[tuple[Any, Any], ...]
+
+
+class _PortableUndefined:
+    def __repr__(self) -> str:
+        return "PORTABLE_UNDEFINED"
+
+
+PORTABLE_UNDEFINED = _PortableUndefined()
+
+
+def _utf8_key(value: str) -> bytes:
+    return value.encode("utf-8")
+
+
+def _encode_node(value: Any, seen: set[int] | None = None) -> dict[str, Any]:
+    if seen is None:
+        seen = set()
+    if value is PORTABLE_UNDEFINED:
+        return {"t": "undefined"}
+    if value is None:
+        return {"t": "null"}
+    if isinstance(value, bool):
+        return {"t": "bool", "v": value}
+    if isinstance(value, str):
+        return {"t": "string", "v": value}
+    if isinstance(value, int):
+        if abs(value) > _SAFE_INTEGER_MAX:
+            raise PayloadSerializationError("serialize", "$", "integers must be within the portable safe-integer range")
+        return {"t": "int", "v": str(value)}
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise PayloadSerializationError("serialize", "$", "non-finite numbers are not portable")
+        return {"t": "float64", "v": struct.pack(">d", value).hex()}
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return {"t": "bytes", "v": base64.b64encode(bytes(value)).decode("ascii")}
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise PayloadSerializationError("serialize", "$", "dates must include a timezone")
+        utc = value.astimezone(UTC)
+        if utc.microsecond % 1000:
+            raise PayloadSerializationError("serialize", "$", "dates must have millisecond precision")
+        return {"t": "date", "v": utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{utc.microsecond // 1000:03d}Z"}
+    if callable(value):
+        raise PayloadSerializationError("serialize", "$", "callable values are not portable")
+    identity = id(value)
+    if identity in seen:
+        raise PayloadSerializationError("serialize", "$", "cyclic values are not portable")
+    seen.add(identity)
+    try:
+        if isinstance(value, (list, tuple)):
+            return {"t": "list", "v": [_encode_node(entry, seen) for entry in value]}
+        if isinstance(value, PortableMap):
+            return {"t": "map", "v": [[_encode_node(k, seen), _encode_node(v, seen)] for k, v in value.entries]}
+        if isinstance(value, dict):
+            if any(not isinstance(key, str) for key in value):
+                raise PayloadSerializationError("serialize", "$", "object keys must be strings; use PortableMap for other keys")
+            return {
+                "t": "object",
+                "v": [[key, _encode_node(value[key], seen)] for key in sorted(value, key=_utf8_key)],
+            }
+        raise PayloadSerializationError("serialize", "$", "class instances are not portable; use plain data")
+    finally:
+        seen.remove(identity)
+
+
+def _decode_node(node: Any) -> Any:
+    if not isinstance(node, dict) or not isinstance(node.get("t"), str):
+        raise ValueError("invalid portable node")
+    kind = node["t"]
+    if kind == "undefined" and set(node) == {"t"}:
+        return PORTABLE_UNDEFINED
+    if kind == "null" and set(node) == {"t"}:
+        return None
+    value = node.get("v")
+    if kind == "bool" and isinstance(value, bool):
+        return value
+    if kind == "string" and isinstance(value, str):
+        return value
+    if kind == "int" and isinstance(value, str) and re.fullmatch(r"-?(0|[1-9]\d*)", value):
+        parsed_int = int(value)
+        if abs(parsed_int) <= _SAFE_INTEGER_MAX and str(parsed_int) == value:
+            return parsed_int
+    if kind == "float64" and isinstance(value, str) and re.fullmatch(r"[0-9a-f]{16}", value):
+        parsed_float = struct.unpack(">d", bytes.fromhex(value))[0]
+        if math.isfinite(parsed_float):
+            return parsed_float
+    if kind == "bytes" and isinstance(value, str):
+        decoded = base64.b64decode(value, validate=True)
+        if base64.b64encode(decoded).decode("ascii") == value:
+            return decoded
+    if kind == "date" and isinstance(value, str) and re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z", value):
+        parsed_date = datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=UTC)
+        if parsed_date.strftime("%Y-%m-%dT%H:%M:%S.") + f"{parsed_date.microsecond // 1000:03d}Z" == value:
+            return parsed_date
+    if kind == "list" and isinstance(value, list):
+        return [_decode_node(entry) for entry in value]
+    if kind == "object" and isinstance(value, list):
+        result: dict[str, Any] = {}
+        previous: bytes | None = None
+        for pair in value:
+            if not isinstance(pair, list) or len(pair) != 2 or not isinstance(pair[0], str):
+                raise ValueError("invalid object entry")
+            encoded_key = pair[0].encode("utf-8")
+            if previous is not None and previous >= encoded_key:
+                raise ValueError("object keys are not canonical")
+            previous = encoded_key
+            result[pair[0]] = _decode_node(pair[1])
+        return result
+    if kind == "map" and isinstance(value, list):
+        entries = []
+        for pair in value:
+            if not isinstance(pair, list) or len(pair) != 2:
+                raise ValueError("invalid map entry")
+            entries.append((_decode_node(pair[0]), _decode_node(pair[1])))
+        return PortableMap(tuple(entries))
+    raise ValueError(f"invalid portable node type '{kind}'")
+
+
+def _validated_metadata(metadata: dict[str, str]) -> list[tuple[str, str]]:
+    entries = sorted(metadata.items(), key=lambda item: item[0].encode("utf-8"))
+    if len(entries) > MAX_PAYLOAD_METADATA_ENTRIES:
+        raise PayloadSerializationError("serialize", "metadata", "too many entries")
+    total = 0
+    for key, value in entries:
+        if not isinstance(key, str) or not _META_KEY_RE.fullmatch(key) or not isinstance(value, str):
+            raise PayloadSerializationError("serialize", "metadata", "contains an invalid key or value")
+        encoded_value = value.encode("utf-8")
+        if len(encoded_value) > 1024:
+            raise PayloadSerializationError("serialize", "metadata", "value exceeds 1024 UTF-8 bytes")
+        total += len(key.encode("utf-8")) + len(encoded_value)
+    if total > MAX_PAYLOAD_METADATA_BYTES:
+        raise PayloadSerializationError("serialize", "metadata", "exceeds the byte limit")
+    return entries
+
+
+def encode_portable_payload(value: Any, metadata: dict[str, str] | None = None) -> bytes:
+    from .v1 import types_pb2
+
+    try:
+        body = json.dumps(_encode_node(value), separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        if len(body) > MAX_PAYLOAD_BODY_BYTES:
+            raise PayloadSerializationError("serialize", "$", "payload exceeds 16 MiB")
+        envelope = types_pb2.PayloadEnvelope(
+            magic=PAYLOAD_MAGIC,
+            envelope_version=PAYLOAD_ENVELOPE_VERSION,
+            encoding="identity",
+            content_type=PAYLOAD_CONTENT_TYPE,
+            codec_name=PAYLOAD_CODEC_NAME,
+            codec_version=PAYLOAD_CODEC_VERSION,
+            body_length=len(body),
+            body_sha256=hashlib.sha256(body).digest(),
+            body=body,
+        )
+        for key, metadata_value in _validated_metadata(metadata or {}):
+            envelope.metadata.add(key=key, value=metadata_value)
+        return envelope.SerializeToString(deterministic=True)
+    except PayloadSerializationError:
+        raise
+    except (TypeError, ValueError, UnicodeError, OverflowError, RecursionError) as exc:
+        raise PayloadSerializationError("serialize", "$", "value could not be inspected safely") from exc
+
+
+def is_portable_envelope(value: bytes) -> bool:
+    return len(value) >= len(_ENVELOPE_PREFIX) and value.startswith(_ENVELOPE_PREFIX)
+
+
+def decode_portable_payload(value: bytes) -> Any:
+    from .v1 import types_pb2
+
+    try:
+        if not is_portable_envelope(value):
+            raise ValueError("payload is missing the MFP1 envelope magic")
+        envelope = types_pb2.PayloadEnvelope.FromString(value)
+        if envelope.magic != PAYLOAD_MAGIC:
+            raise ValueError("invalid payload magic")
+        if envelope.envelope_version != PAYLOAD_ENVELOPE_VERSION:
+            raise ValueError(f"unsupported envelope version {envelope.envelope_version}")
+        if (
+            envelope.encoding != "identity"
+            or envelope.content_type != PAYLOAD_CONTENT_TYPE
+            or envelope.codec_name != PAYLOAD_CODEC_NAME
+            or envelope.codec_version != PAYLOAD_CODEC_VERSION
+        ):
+            raise ValueError("unsupported payload codec contract")
+        if envelope.HasField("blob"):
+            raise ValueError("blob-backed envelope requires server-side resolution")
+        if envelope.HasField("encryption"):
+            raise ValueError("encrypted envelope requires a configured decryptor")
+        if envelope.body_length != len(envelope.body) or len(envelope.body) > MAX_PAYLOAD_BODY_BYTES:
+            raise ValueError("payload body length mismatch")
+        if len(envelope.body_sha256) != 32 or not hashlib.sha256(envelope.body).digest() == envelope.body_sha256:
+            raise ValueError("payload SHA-256 mismatch")
+        metadata_entries = [(entry.key, entry.value) for entry in envelope.metadata]
+        if metadata_entries != sorted(metadata_entries, key=lambda item: item[0].encode("utf-8")):
+            raise ValueError("payload metadata keys are not canonical")
+        metadata = dict(metadata_entries)
+        if len(metadata) != len(envelope.metadata):
+            raise ValueError("duplicate payload metadata key")
+        _validated_metadata(metadata)
+        parsed = json.loads(envelope.body.decode("utf-8"), parse_constant=_reject_non_json_constant)
+        decoded = _decode_node(parsed)
+        canonical = json.dumps(_encode_node(decoded), separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        if canonical != envelope.body:
+            raise ValueError("payload body is not canonical")
+        return decoded
+    except DecodeError as exc:
+        raise PayloadDeserializationError("deserialize", "$", "invalid payload envelope") from exc
+    except PayloadSerializationError as exc:
+        raise PayloadDeserializationError("deserialize", "$", str(exc)) from exc
+    except (TypeError, ValueError, UnicodeError, OverflowError, RecursionError) as exc:
+        raise PayloadDeserializationError("deserialize", "$", str(exc)) from exc
+
+
+def serialize(value: Any) -> bytes:
+    return encode_portable_payload(value)
+
+
+def serialize_step_output(step_name: str, value: Any) -> bytes:
+    from .payload_codec import codecs
+
+    return serialize(codecs.envelope_for(step_name, value))
+
+
+def _reject_non_json_constant(value: str) -> Any:
+    raise ValueError(f"non-JSON numeric constant {value}")
+
+
+def _validate_legacy_json_limits(value: bytes) -> None:
+    if len(value) > MAX_PAYLOAD_BODY_BYTES:
+        raise ValueError("legacy JSON payload exceeds 16 MiB")
+    depth = 0
+    in_string = False
+    escaped = False
+    for byte in value:
+        if in_string:
+            if escaped:
+                escaped = False
+            elif byte == 0x5C:
+                escaped = True
+            elif byte == 0x22:
+                in_string = False
+        elif byte == 0x22:
+            in_string = True
+        elif byte in (0x5B, 0x7B):
+            depth += 1
+            if depth > MAX_LEGACY_JSON_DEPTH:
+                raise ValueError("legacy JSON payload exceeds the nesting limit")
+        elif byte in (0x5D, 0x7D):
+            depth = max(0, depth - 1)
+
+
+def deserialize(buf: bytes | None) -> Any:
+    if buf is None:
+        return None
+    if not isinstance(buf, bytes):
+        raise PayloadDeserializationError("deserialize", "$", "value must be bytes")
+    if len(buf) == 0:
+        return None
+    if is_portable_envelope(buf):
+        return decode_portable_payload(buf)
+    # Explicit decode-only compatibility for pre-envelope payloads.
+    try:
+        _validate_legacy_json_limits(buf)
+        return json.loads(buf.decode("utf-8"), parse_constant=_reject_non_json_constant)
+    except (TypeError, ValueError, UnicodeError, RecursionError) as exc:
+        raise PayloadDeserializationError("deserialize", "$", "bytes are not valid JSON") from exc
+
+
+def deserialize_step_output(step_name: str, buf: bytes | None) -> Any:
+    from .payload_codec import codecs
+
+    return codecs.hydrate(step_name, deserialize(buf))
+
+
+def serialize_error(error: BaseException) -> tuple[str, str]:
+    """(error_type, error_message) — error_type is the exception class name,
+    mirroring the TS SDK's constructor-name convention. NonDeterminismError's
+    name is load-bearing (P11.2 blocked transition)."""
+    if isinstance(error, MemoflowSdkError):
+        try:
+            error_type = error.code if isinstance(error.code, str) and error.code.strip() else "MemoflowSdkError"
+            message = str(error)
+        except Exception:
+            return "MemoflowSdkError", "MemoflowSdkError value could not be inspected"
+        return error_type, message if message.strip() else error_type
+    error_type = type(error).__name__ or "Exception"
+    try:
+        message = str(error)
+    except Exception:
+        message = "Exception value could not be stringified"
+    return error_type, message if message.strip() else error_type
+
+
+class StepError(Exception):
+    """A memoized FAILED step replayed on recovery. `error_type` carries the
+    original error's type name."""
+
+    def __init__(self, error_type: str, message: str):
+        self.error_type = error_type
+        super().__init__(message)
+
+
+def parse_duration(duration: str) -> int:
+    """Duration string ("5s", "1m", "100ms", "2h", "1d") -> milliseconds.
+    Same grammar as the TS SDK's parseDuration."""
+    if not isinstance(duration, str):
+        raise ProtocolValidationError("parse_duration", "duration", _DURATION_FORMAT_REASON)
+    m = _DURATION_RE.match(duration)
+    if not m:
+        raise ProtocolValidationError("parse_duration", "duration", _DURATION_FORMAT_REASON)
+
+    numeric_text = m.group(1)
+    if len(numeric_text) > 64:
+        raise ProtocolValidationError("parse_duration", "duration", _DURATION_VALUE_REASON)
+    whole, separator, fraction = numeric_text.partition(".")
+    if not separator:
+        fraction = ""
+    try:
+        numerator: int = int(f"{whole}{fraction}") * _UNIT_MS[m.group(2)]
+        denominator: int = 10 ** len(fraction)
+        milliseconds: int
+        remainder: int
+        milliseconds, remainder = divmod(numerator, denominator)
+    except (ValueError, OverflowError) as exc:
+        raise ProtocolValidationError("parse_duration", "duration", _DURATION_VALUE_REASON) from exc
+    if remainder != 0 or milliseconds <= 0 or milliseconds > _MAX_PROTOBUF_DURATION_MS:
+        raise ProtocolValidationError("parse_duration", "duration", _DURATION_VALUE_REASON)
+    return milliseconds