velophex 0.2.0__py3-none-any.whl

velophex/contracts/executor.py

@@ -0,0 +1,1921 @@
+"""Executor protocol messages (ADR-P005, ``docs/EXECUTOR-PROTOCOL.md``, protocol version 1, revision 1.1).
+
+Every message is an envelope ``{"type": name, "body": {...}}``. The bodies here mirror the
+records in ``VeloPhex.Platform.Executor.Protocol.ExecutorMessages`` *member for member and in
+their declared order*, because the conformance vectors in
+``schemas/test-vectors/executor-frames.json`` compare payload bytes, not parsed objects.
+
+Bodies are camelCase and omit null members. A member that is non-nullable in .NET (a ``bool``
+or an ``int``) is always written, even at its default — that is why ``retryable: false``
+appears in the fault vector.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any, ClassVar, Final
+from uuid import UUID
+
+from velophex import _json
+from velophex._json import omit_none
+
+__all__ = [
+    "ABSOLUTE_MAXIMUM_FRAME_BYTES",
+    "CURRENT_VERSION",
+    "DEFAULT_MAXIMUM_FRAME_BYTES",
+    "FAULT_ENVELOPE_VERSION",
+    "FRAME_HEADER_BYTES",
+    "FRAME_LENGTH_BYTES",
+    "FRAME_TAG_BYTES",
+    "MINIMUM_VERSION",
+    "REVISION",
+    "SESSION_KEY_BYTES",
+    "SESSION_KEY_ENVIRONMENT_VARIABLE",
+    "TAG_LABEL",
+    "BookmarkInfo",
+    "BookmarkKinds",
+    "BreakpointInfo",
+    "CanceledMessage",
+    "CheckpointInfo",
+    "CheckpointMessage",
+    "CheckpointedMessage",
+    "DebugCommandMessage",
+    "DebugCommands",
+    "DebugExceptionInfo",
+    "DebugFrameInfo",
+    "DebugLocation",
+    "DebugOptionKeys",
+    "DebugOptions",
+    "DebugPauseReasons",
+    "DebugPausedMessage",
+    "DebugRestartedMessage",
+    "DebugResumedMessage",
+    "DebugSettings",
+    "DebugStepOutputs",
+    "DebugTraceMessage",
+    "DebugTraceStates",
+    "DebugVariableInfo",
+    "DebugVariablesMessage",
+    "EvaluateResultMessage",
+    "ExecutionContextInfo",
+    "ExecutorCapabilities",
+    "ExecutorFrameDirection",
+    "ExecutorMessage",
+    "ExecutorProtocolError",
+    "ExecutorProtocolException",
+    "FaultInfo",
+    "FaultMessage",
+    "FaultRetryScopes",
+    "HeartbeatMessage",
+    "HelloAckMessage",
+    "HelloMessage",
+    "LogMessage",
+    "PrepareMessage",
+    "PreparedMessage",
+    "ProgressMessage",
+    "RestoreMessage",
+    "ResultMessage",
+    "ResumeBookmarkMessage",
+    "RuntimeHealthMessage",
+    "RuntimeHealthReportMessage",
+    "RuntimeHealthStatuses",
+    "StartMessage",
+    "StopMessage",
+    "SubInvokeMessage",
+    "SubResultMessage",
+    "SuspendedMessage",
+    "TestAssertionInfo",
+    "TestOutcomes",
+    "TestResultMessage",
+    "decode_message",
+    "encode_message",
+    "format_timestamp",
+    "message_type_name",
+    "parse_timestamp",
+    "select_version",
+]
+
+CURRENT_VERSION: Final = 1
+MINIMUM_VERSION: Final = 1
+
+#: The specification revision these models are built against. Additive revisions keep the wire
+#: version: every addition sits behind a capability, so this string says which contract the SDK
+#: was built from, not which optional features the worker implements. The worker offers none of
+#: the ``debug-*`` capabilities and none of the revision 2 ones: a Python automation is a function
+#: call and nothing in it suspends, so it answers ``checkpoint``, ``restore``, ``resume-bookmark``
+#: and ``runtime-health`` as unsupported rather than misparsing them.
+#:
+#: This pinned ``1.1`` while .NET was at ``1.2`` and nothing compared the two, so the SDK claimed a
+#: revision it was not built against and no test could say so. ``test_vocabulary_mirror`` now reads
+#: ``ExecutorProtocol.Revision`` from the C# source and fails on a mismatch.
+REVISION: Final = "2.0"
+
+SESSION_KEY_ENVIRONMENT_VARIABLE: Final = "VELOPHEX_EXECUTOR_SESSION_KEY"
+SESSION_KEY_BYTES: Final = 32
+
+FRAME_LENGTH_BYTES: Final = 4
+FRAME_TAG_BYTES: Final = 32
+FRAME_HEADER_BYTES: Final = FRAME_LENGTH_BYTES + FRAME_TAG_BYTES
+
+DEFAULT_MAXIMUM_FRAME_BYTES: Final = 16 * 1024 * 1024
+ABSOLUTE_MAXIMUM_FRAME_BYTES: Final = 256 * 1024 * 1024
+
+#: Domain separator bound into every tag; the trailing NUL is part of it.
+TAG_LABEL: Final = b"VPXEX/1\x00"
+
+
+class ExecutorFrameDirection:
+    """Which side wrote a frame. Bound into the tag, so a frame is valid one way only."""
+
+    PARENT_TO_EXECUTOR: Final = 1
+    EXECUTOR_TO_PARENT: Final = 2
+
+
+class ExecutorCapabilities:
+    """Optional features an executor or parent announces in the hello exchange."""
+
+    PREPARE: Final = "prepare"
+    DEBUG: Final = "debug"
+    PROGRESS: Final = "progress"
+    SUB_INVOKE: Final = "sub-invoke"
+
+    # Revision 1.1 debugger features (offered by an executor).
+    DEBUG_EXCEPTIONS: Final = "debug-exceptions"
+    DEBUG_SLOW_STEP: Final = "debug-slow-step"
+    DEBUG_LOG_ACTIVITIES: Final = "debug-log-activities"
+    DEBUG_TRAIL: Final = "debug-trail"
+    DEBUG_ACTIVITY_OPTIONS: Final = "debug-options"
+    DEBUG_STEP_INTO_INVOKE: Final = "debug-step-into-invoke"
+    DEBUG_RUN_TO: Final = "debug-run-to"
+    DEBUG_RUN_FROM: Final = "debug-run-from"
+    DEBUG_VARIABLES: Final = "debug-variables"
+    DEBUG_BRANCHES: Final = "debug-branches"
+
+    # Contracts 0.8.16 (engine ADR 0037 section 6): handles ``request-stop``. The worker offers it.
+    SHOULD_STOP: Final = "should-stop"
+
+    # Contracts 0.8.25: a parent opts in to test mode and ``test-result`` messages. The worker does
+    # not offer it; a Python test case runs as a plain entry point.
+    TEST_RESULTS: Final = "test-results"
+
+
+class DebugCommands:
+    """Commands a debugging parent sends."""
+
+    CONTINUE: Final = "Continue"
+    STEP_INTO: Final = "StepInto"
+    STEP_OVER: Final = "StepOver"
+    STEP_OUT: Final = "StepOut"
+    PAUSE: Final = "Pause"
+    SET_BREAKPOINTS: Final = "SetBreakpoints"
+    EVALUATE: Final = "Evaluate"
+    RETRY: Final = "Retry"
+    IGNORE: Final = "Ignore"
+    RESTART: Final = "Restart"
+    RUN_TO: Final = "RunTo"
+    GET_CHILDREN: Final = "GetChildren"
+    SET_VARIABLE: Final = "SetVariable"
+    SET_SETTINGS: Final = "SetSettings"
+
+
+class DebugPauseReasons:
+    """The ``reason`` of ``debug-paused``."""
+
+    ENTRY: Final = "Entry"
+    BREAKPOINT: Final = "Breakpoint"
+    STEP: Final = "Step"
+    PAUSE: Final = "Pause"
+    EXCEPTION: Final = "Exception"
+    RUN_TO: Final = "RunTo"
+
+
+class DebugTraceStates:
+    """The ``state`` of ``debug-trace``."""
+
+    STARTED: Final = "Started"
+    COMPLETED: Final = "Completed"
+    FAULTED: Final = "Faulted"
+    SKIPPED: Final = "Skipped"
+
+
+class DebugOptionKeys:
+    """Well-known keys of ``DebugSettings.options``."""
+
+    HIGHLIGHT_ELEMENTS: Final = "highlightElements"
+
+
+class ExecutorProtocolError:
+    """Why a frame or message was rejected. Mirrors the .NET ``ExecutorProtocolError`` enum."""
+
+    INVALID_LENGTH: Final = "InvalidLength"
+    PAYLOAD_TOO_LARGE: Final = "PayloadTooLarge"
+    TRUNCATED_FRAME: Final = "TruncatedFrame"
+    AUTHENTICATION_FAILED: Final = "AuthenticationFailed"
+    MALFORMED_MESSAGE: Final = "MalformedMessage"
+    UNKNOWN_MESSAGE_TYPE: Final = "UnknownMessageType"
+
+
+class ExecutorProtocolException(Exception):
+    """A protocol violation. The channel is closed and the parent kills the executor."""
+
+    def __init__(self, error: str, message: str) -> None:
+        super().__init__(message)
+        self.error = error
+
+
+# --------------------------------------------------------------------------- timestamps
+
+_FRACTION = re.compile(r"\.(\d+)")
+
+
+def format_timestamp(value: datetime) -> _json.VerbatimString:
+    r"""Format *value* the way ``System.Text.Json`` writes a ``DateTimeOffset``.
+
+    ``yyyy-MM-ddTHH:mm:ss[.fffffff]+HH:MM``: the fraction is dropped when it is zero and
+    otherwise carries no trailing zeros, and UTC is written as ``+00:00`` rather than ``Z``.
+    A naive value is read as UTC, because the protocol has no local time.
+
+    The result is a :class:`velophex._json.VerbatimString`, because .NET writes a
+    ``DateTimeOffset`` through a typed fast path that never reaches the escaping encoder: the
+    ``+`` of the offset stays a ``+`` where the same text in a plain string property would
+    become ``+``. The frame vectors depend on it.
+    """
+    moment = value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+    text = (
+        f"{moment.year:04d}-{moment.month:02d}-{moment.day:02d}"
+        f"T{moment.hour:02d}:{moment.minute:02d}:{moment.second:02d}"
+    )
+
+    if moment.microsecond:
+        text += f".{moment.microsecond:06d}".rstrip("0")
+
+    offset = moment.utcoffset() or timedelta(0)
+    total_minutes = int(offset.total_seconds() // 60)
+    sign = "-" if total_minutes < 0 else "+"
+    total_minutes = abs(total_minutes)
+
+    return _json.VerbatimString(f"{text}{sign}{total_minutes // 60:02d}:{total_minutes % 60:02d}")
+
+
+def parse_timestamp(value: str) -> datetime:
+    """Parse an ISO 8601 timestamp, tolerating ``Z`` and the 7 fractional digits .NET writes."""
+    text = value.strip()
+
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+
+    # datetime.fromisoformat accepts 3 or 6 fractional digits only.
+    def _trim(match: re.Match[str]) -> str:
+        digits = match.group(1)
+        return "." + (digits[:6].ljust(6, "0"))
+
+    text = _FRACTION.sub(_trim, text, count=1)
+
+    parsed = datetime.fromisoformat(text)
+    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
+
+
+def _timestamp(body: dict[str, Any], name: str) -> datetime | None:
+    raw = body.get(name)
+    return parse_timestamp(raw) if isinstance(raw, str) else None
+
+
+def _uuid(body: dict[str, Any], name: str) -> UUID | None:
+    raw = body.get(name)
+    return UUID(raw) if isinstance(raw, str) else None
+
+
+# --------------------------------------------------------------------------- payload types
+
+
+#: ``FaultInfo.version`` of a fault that carries the envelope members (contracts 0.8.37).
+FAULT_ENVELOPE_VERSION: Final = 2
+
+
+class FaultRetryScopes:
+    """What a retry of a failed run would repeat (``FaultInfo.retry_scope``)."""
+
+    #: Nothing safely: an effect was committed or the failure is deterministic.
+    NONE: Final = "none"
+
+    #: Only a model call failed and nothing was changed.
+    MODEL_CALL: Final = "model-call"
+
+    #: The whole run may be started again.
+    RUN: Final = "run"
+
+
+@dataclass(frozen=True, slots=True)
+class FaultInfo:
+    """Why a run failed. ``kind`` is one of ``FaultKinds`` and decides whether it is retried.
+
+    ``code`` names the condition and is distinct from ``kind``. The members after ``retryable``
+    are the fault envelope (``version`` 2, contracts 0.8.37), each absent from the wire when
+    unset, so a version-1 fault keeps its exact bytes.
+    """
+
+    kind: str
+    code: str
+    message: str
+    detail: str | None = None
+    retryable: bool = True
+    version: int | None = None
+    cause: str | None = None
+    fix: str | None = None
+    retry_scope: str | None = None
+    request_id: str | None = None
+    docs_url: str | None = None
+    effects_committed: bool | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``FaultInfo`` record."""
+        return omit_none(
+            {
+                "kind": self.kind,
+                "code": self.code,
+                "message": self.message,
+                "detail": self.detail,
+                "retryable": self.retryable,
+                "version": self.version,
+                "cause": self.cause,
+                "fix": self.fix,
+                "retryScope": self.retry_scope,
+                "requestId": self.request_id,
+                "docsUrl": self.docs_url,
+                "effectsCommitted": self.effects_committed,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> FaultInfo:
+        """Read a fault from its body."""
+        version = body.get("version")
+        committed = body.get("effectsCommitted")
+
+        return cls(
+            kind=str(body["kind"]),
+            code=str(body["code"]),
+            message=str(body["message"]),
+            detail=body.get("detail"),
+            retryable=bool(body.get("retryable", True)),
+            version=int(version) if version is not None else None,
+            cause=body.get("cause"),
+            fix=body.get("fix"),
+            retry_scope=body.get("retryScope"),
+            request_id=body.get("requestId"),
+            docs_url=body.get("docsUrl"),
+            effects_committed=bool(committed) if committed is not None else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BreakpointInfo:
+    """A breakpoint on a workflow element id."""
+
+    node_id: str
+    condition: str | None = None
+    hit_count: int | None = None
+    log_message: str | None = None
+    workflow_path: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``BreakpointInfo`` record."""
+        return omit_none(
+            {
+                "nodeId": self.node_id,
+                "condition": self.condition,
+                "hitCount": self.hit_count,
+                "logMessage": self.log_message,
+                "workflowPath": self.workflow_path,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> BreakpointInfo:
+        """Read a breakpoint from its body."""
+        return cls(
+            node_id=str(body["nodeId"]),
+            condition=body.get("condition"),
+            hit_count=int(body["hitCount"]) if body.get("hitCount") is not None else None,
+            log_message=body.get("logMessage"),
+            workflow_path=body.get("workflowPath"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugLocation:
+    """An element of a workflow file (revision 1.1)."""
+
+    node_id: str
+    workflow_path: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugLocation`` record."""
+        return omit_none({"nodeId": self.node_id, "workflowPath": self.workflow_path})
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugLocation:
+        """Read a location from its body."""
+        return cls(node_id=str(body["nodeId"]), workflow_path=body.get("workflowPath"))
+
+
+def _optional_location(body: dict[str, Any], name: str) -> DebugLocation | None:
+    value = body.get(name)
+    return DebugLocation.from_json_value(value) if isinstance(value, dict) else None
+
+
+def _optional_bool(body: dict[str, Any], name: str) -> bool | None:
+    value = body.get(name)
+    return bool(value) if value is not None else None
+
+
+def _optional_int(body: dict[str, Any], name: str) -> int | None:
+    value = body.get(name)
+    return int(value) if value is not None else None
+
+
+@dataclass(frozen=True, slots=True)
+class DebugSettings:
+    """Debug behaviour set at start or changed by ``SetSettings`` (revision 1.1)."""
+
+    break_on_exceptions: bool | None = None
+    break_on_caught_exceptions: bool | None = None
+    step_delay_milliseconds: int | None = None
+    log_activities: bool | None = None
+    execution_trail: bool | None = None
+    options: dict[str, Any] | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugSettings`` record."""
+        return omit_none(
+            {
+                "breakOnExceptions": self.break_on_exceptions,
+                "breakOnCaughtExceptions": self.break_on_caught_exceptions,
+                "stepDelayMilliseconds": self.step_delay_milliseconds,
+                "logActivities": self.log_activities,
+                "executionTrail": self.execution_trail,
+                "options": dict(self.options) if self.options is not None else None,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugSettings:
+        """Read debug settings from their body."""
+        options = body.get("options")
+
+        return cls(
+            break_on_exceptions=_optional_bool(body, "breakOnExceptions"),
+            break_on_caught_exceptions=_optional_bool(body, "breakOnCaughtExceptions"),
+            step_delay_milliseconds=_optional_int(body, "stepDelayMilliseconds"),
+            log_activities=_optional_bool(body, "logActivities"),
+            execution_trail=_optional_bool(body, "executionTrail"),
+            options=dict(options) if isinstance(options, dict) else None,
+        )
+
+
+def _optional_settings(body: dict[str, Any], name: str) -> DebugSettings | None:
+    value = body.get(name)
+    return DebugSettings.from_json_value(value) if isinstance(value, dict) else None
+
+
+@dataclass(frozen=True, slots=True)
+class DebugOptions:
+    """Debugging asked for at start."""
+
+    breakpoints: list[BreakpointInfo] = field(default_factory=list)
+    stop_on_entry: bool = False
+    settings: DebugSettings | None = None
+    run_to: DebugLocation | None = None
+    start_at: DebugLocation | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugOptions`` record."""
+        return omit_none(
+            {
+                "breakpoints": [breakpoint.to_json_value() for breakpoint in self.breakpoints],
+                "stopOnEntry": self.stop_on_entry,
+                "settings": self.settings.to_json_value() if self.settings is not None else None,
+                "runTo": self.run_to.to_json_value() if self.run_to is not None else None,
+                "startAt": self.start_at.to_json_value() if self.start_at is not None else None,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugOptions:
+        """Read debug options from their body."""
+        return cls(
+            breakpoints=[BreakpointInfo.from_json_value(item) for item in body.get("breakpoints") or []],
+            stop_on_entry=bool(body.get("stopOnEntry", False)),
+            settings=_optional_settings(body, "settings"),
+            run_to=_optional_location(body, "runTo"),
+            start_at=_optional_location(body, "startAt"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionContextInfo:
+    """Who is running and on whose behalf.
+
+    ``runtime_token`` authorises the Orchestrator Runtime API for this attempt only. The
+    worker keeps it in memory, never logs it, never puts it in a child process's environment
+    and never returns it in outputs.
+    """
+
+    job_id: UUID | None = None
+    attempt_id: UUID | None = None
+    attempt_number: int = 0
+    orchestrator_url: str | None = None
+    runtime_token: str | None = None
+    runtime_token_expires_at: datetime | None = None
+    deadline: datetime | None = None
+    robot_name: str | None = None
+    machine_name: str | None = None
+    trace_parent: str | None = None
+    trace_state: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``ExecutionContextInfo`` record."""
+        return omit_none(
+            {
+                "jobId": str(self.job_id) if self.job_id else None,
+                "attemptId": str(self.attempt_id) if self.attempt_id else None,
+                "attemptNumber": self.attempt_number,
+                "orchestratorUrl": self.orchestrator_url,
+                "runtimeToken": self.runtime_token,
+                "runtimeTokenExpiresAt": _optional_timestamp(self.runtime_token_expires_at),
+                "deadline": _optional_timestamp(self.deadline),
+                "robotName": self.robot_name,
+                "machineName": self.machine_name,
+                "traceParent": self.trace_parent,
+                "traceState": self.trace_state,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> ExecutionContextInfo:
+        """Read the execution context from its body."""
+        return cls(
+            job_id=_uuid(body, "jobId"),
+            attempt_id=_uuid(body, "attemptId"),
+            attempt_number=int(body.get("attemptNumber", 0)),
+            orchestrator_url=body.get("orchestratorUrl"),
+            runtime_token=body.get("runtimeToken"),
+            runtime_token_expires_at=_timestamp(body, "runtimeTokenExpiresAt"),
+            deadline=_timestamp(body, "deadline"),
+            robot_name=body.get("robotName"),
+            machine_name=body.get("machineName"),
+            trace_parent=body.get("traceParent"),
+            trace_state=body.get("traceState"),
+        )
+
+    def redacted(self) -> ExecutionContextInfo:
+        """A copy without the runtime token, safe to log or hand to automation code."""
+        return ExecutionContextInfo(
+            job_id=self.job_id,
+            attempt_id=self.attempt_id,
+            attempt_number=self.attempt_number,
+            orchestrator_url=self.orchestrator_url,
+            runtime_token=None,
+            runtime_token_expires_at=self.runtime_token_expires_at,
+            deadline=self.deadline,
+            robot_name=self.robot_name,
+            machine_name=self.machine_name,
+            trace_parent=self.trace_parent,
+            trace_state=self.trace_state,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugVariableInfo:
+    """One local in a paused frame."""
+
+    name: str
+    type_name: str | None = None
+    value: str | None = None
+    is_sensitive: bool = False
+    reference: int | None = None
+    child_count: int | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugVariableInfo`` record."""
+        return omit_none(
+            {
+                "name": self.name,
+                "typeName": self.type_name,
+                "value": self.value,
+                "isSensitive": self.is_sensitive,
+                "reference": self.reference,
+                "childCount": self.child_count,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugVariableInfo:
+        """Read a local from its body."""
+        return cls(
+            name=str(body["name"]),
+            type_name=body.get("typeName"),
+            value=body.get("value"),
+            is_sensitive=bool(body.get("isSensitive", False)),
+            reference=_optional_int(body, "reference"),
+            child_count=_optional_int(body, "childCount"),
+        )
+
+
+def _variables(body: dict[str, Any], name: str) -> list[DebugVariableInfo]:
+    return [DebugVariableInfo.from_json_value(item) for item in body.get(name) or []]
+
+
+@dataclass(frozen=True, slots=True)
+class DebugFrameInfo:
+    """One frame of a paused call stack."""
+
+    node_id: str
+    display_name: str | None = None
+    workflow_path: str | None = None
+    is_faulted: bool | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugFrameInfo`` record."""
+        return omit_none(
+            {
+                "nodeId": self.node_id,
+                "displayName": self.display_name,
+                "workflowPath": self.workflow_path,
+                "isFaulted": self.is_faulted,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugFrameInfo:
+        """Read a call stack frame from its body."""
+        return cls(
+            node_id=str(body["nodeId"]),
+            display_name=body.get("displayName"),
+            workflow_path=body.get("workflowPath"),
+            is_faulted=_optional_bool(body, "isFaulted"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugExceptionInfo:
+    """The exception a run paused on (revision 1.1)."""
+
+    type_name: str
+    message: str
+    is_handled: bool
+    code: str | None = None
+    category: str | None = None
+    detail: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugExceptionInfo`` record."""
+        return omit_none(
+            {
+                "typeName": self.type_name,
+                "message": self.message,
+                "isHandled": self.is_handled,
+                "code": self.code,
+                "category": self.category,
+                "detail": self.detail,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugExceptionInfo:
+        """Read exception details from their body."""
+        return cls(
+            type_name=str(body["typeName"]),
+            message=str(body["message"]),
+            is_handled=bool(body["isHandled"]),
+            code=body.get("code"),
+            category=body.get("category"),
+            detail=body.get("detail"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugStepOutputs:
+    """What the last completed element wrote (revision 1.1)."""
+
+    node_id: str
+    display_name: str | None = None
+    outputs: list[DebugVariableInfo] = field(default_factory=list)
+    workflow_path: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``DebugStepOutputs`` record."""
+        return omit_none(
+            {
+                "nodeId": self.node_id,
+                "displayName": self.display_name,
+                "outputs": [output.to_json_value() for output in self.outputs],
+                "workflowPath": self.workflow_path,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugStepOutputs:
+        """Read step outputs from their body."""
+        return cls(
+            node_id=str(body["nodeId"]),
+            display_name=body.get("displayName"),
+            outputs=_variables(body, "outputs"),
+            workflow_path=body.get("workflowPath"),
+        )
+
+
+def _optional_timestamp(value: datetime | None) -> _json.VerbatimString | None:
+    return format_timestamp(value) if value is not None else None
+
+
+# --------------------------------------------------------------------------- messages
+
+
+class ExecutorMessage:
+    """Base of every executor protocol message."""
+
+    #: The ``type`` discriminator of the envelope.
+    type_name: ClassVar[str]
+
+    def to_json_value(self) -> dict[str, Any]:
+        """The message body, members in the order the .NET record declares them."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> ExecutorMessage:
+        """Read the message from its body."""
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class HelloMessage(ExecutorMessage):
+    """Parent to executor: the first frame of a session."""
+
+    type_name: ClassVar[str] = "hello"
+
+    minimum_version: int
+    maximum_version: int
+    parent_name: str
+    parent_version: str
+    capabilities: list[str] = field(default_factory=list)
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``hello``."""
+        return {
+            "minimumVersion": self.minimum_version,
+            "maximumVersion": self.maximum_version,
+            "parentName": self.parent_name,
+            "parentVersion": self.parent_version,
+            "capabilities": list(self.capabilities),
+        }
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> HelloMessage:
+        """Read ``hello`` from its body."""
+        return cls(
+            minimum_version=int(body["minimumVersion"]),
+            maximum_version=int(body["maximumVersion"]),
+            parent_name=str(body["parentName"]),
+            parent_version=str(body["parentVersion"]),
+            capabilities=[str(item) for item in body.get("capabilities") or []],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class HelloAckMessage(ExecutorMessage):
+    """Executor to parent: accepts the session with the highest common version."""
+
+    type_name: ClassVar[str] = "hello-ack"
+
+    version: int
+    runtime: str
+    runtime_version: str
+    executor_version: str
+    capabilities: list[str] = field(default_factory=list)
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``hello-ack``."""
+        return {
+            "version": self.version,
+            "runtime": self.runtime,
+            "runtimeVersion": self.runtime_version,
+            "executorVersion": self.executor_version,
+            "capabilities": list(self.capabilities),
+        }
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> HelloAckMessage:
+        """Read ``hello-ack`` from its body."""
+        return cls(
+            version=int(body["version"]),
+            runtime=str(body["runtime"]),
+            runtime_version=str(body["runtimeVersion"]),
+            executor_version=str(body["executorVersion"]),
+            capabilities=[str(item) for item in body.get("capabilities") or []],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PrepareMessage(ExecutorMessage):
+    """Parent to executor: build the environment for a package under ``environment_root``."""
+
+    type_name: ClassVar[str] = "prepare"
+
+    package_root: str
+    environment_root: str
+    settings: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``prepare``."""
+        return omit_none(
+            {
+                "packageRoot": self.package_root,
+                "environmentRoot": self.environment_root,
+                "settings": self.settings,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> PrepareMessage:
+        """Read ``prepare`` from its body."""
+        return cls(
+            package_root=str(body["packageRoot"]),
+            environment_root=str(body["environmentRoot"]),
+            settings=body.get("settings"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedMessage(ExecutorMessage):
+    """Executor to parent: the environment is ready."""
+
+    type_name: ClassVar[str] = "prepared"
+
+    environment_root: str
+    fingerprint: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``prepared``."""
+        return omit_none({"environmentRoot": self.environment_root, "fingerprint": self.fingerprint})
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> PreparedMessage:
+        """Read ``prepared`` from its body."""
+        return cls(environment_root=str(body["environmentRoot"]), fingerprint=body.get("fingerprint"))
+
+
+@dataclass(frozen=True, slots=True)
+class StartMessage(ExecutorMessage):
+    """Parent to executor: run one entry point of the extracted package."""
+
+    type_name: ClassVar[str] = "start"
+
+    package_root: str
+    entry_point_id: str
+    context: ExecutionContextInfo
+    environment_root: str | None = None
+    inputs: Any | None = None
+    debug: DebugOptions | None = None
+    #: The tenant expression policy (engine ADR 0036), kept as read; Python has no expressions.
+    expression_policy: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``start``."""
+        return omit_none(
+            {
+                "packageRoot": self.package_root,
+                "environmentRoot": self.environment_root,
+                "entryPointId": self.entry_point_id,
+                "inputs": self.inputs,
+                "context": self.context.to_json_value(),
+                "debug": self.debug.to_json_value() if self.debug is not None else None,
+                "expressionPolicy": self.expression_policy,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> StartMessage:
+        """Read ``start`` from its body."""
+        debug = body.get("debug")
+
+        return cls(
+            package_root=str(body["packageRoot"]),
+            entry_point_id=str(body["entryPointId"]),
+            context=ExecutionContextInfo.from_json_value(body.get("context") or {}),
+            environment_root=body.get("environmentRoot"),
+            inputs=body.get("inputs"),
+            debug=DebugOptions.from_json_value(debug) if isinstance(debug, dict) else None,
+            expression_policy=body.get("expressionPolicy"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StopMessage(ExecutorMessage):
+    """Parent to executor: end gracefully within the grace period, or be killed."""
+
+    type_name: ClassVar[str] = "stop"
+
+    reason: str
+    grace_period_milliseconds: int
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``stop``."""
+        return {"reason": self.reason, "gracePeriodMilliseconds": self.grace_period_milliseconds}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> StopMessage:
+        """Read ``stop`` from its body."""
+        return cls(reason=str(body["reason"]), grace_period_milliseconds=int(body["gracePeriodMilliseconds"]))
+
+
+@dataclass(frozen=True, slots=True)
+class LogMessage(ExecutorMessage):
+    """Executor to parent: one log line of the automation or the worker."""
+
+    type_name: ClassVar[str] = "log"
+
+    sequence: int
+    timestamp: datetime
+    level: str
+    message: str
+    phase: str | None = None
+    sub_phase: str | None = None
+    node_id: str | None = None
+    details: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``log``."""
+        return omit_none(
+            {
+                "sequence": self.sequence,
+                "timestamp": format_timestamp(self.timestamp),
+                "level": self.level,
+                "message": self.message,
+                "phase": self.phase,
+                "subPhase": self.sub_phase,
+                "nodeId": self.node_id,
+                "details": self.details,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> LogMessage:
+        """Read ``log`` from its body."""
+        return cls(
+            sequence=int(body["sequence"]),
+            timestamp=parse_timestamp(str(body["timestamp"])),
+            level=str(body["level"]),
+            message=str(body["message"]),
+            phase=body.get("phase"),
+            sub_phase=body.get("subPhase"),
+            node_id=body.get("nodeId"),
+            details=body.get("details"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ProgressMessage(ExecutorMessage):
+    """Executor to parent: an element started, completed or faulted."""
+
+    type_name: ClassVar[str] = "progress"
+
+    node_id: str
+    state: str
+    timestamp: datetime
+    display_name: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``progress``."""
+        return omit_none(
+            {
+                "nodeId": self.node_id,
+                "displayName": self.display_name,
+                "state": self.state,
+                "timestamp": format_timestamp(self.timestamp),
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> ProgressMessage:
+        """Read ``progress`` from its body."""
+        return cls(
+            node_id=str(body["nodeId"]),
+            state=str(body["state"]),
+            timestamp=parse_timestamp(str(body["timestamp"])),
+            display_name=body.get("displayName"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class HeartbeatMessage(ExecutorMessage):
+    """Executor to parent: liveness while an activity runs for a long time."""
+
+    type_name: ClassVar[str] = "heartbeat"
+
+    timestamp: datetime
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``heartbeat``."""
+        return {"timestamp": format_timestamp(self.timestamp)}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> HeartbeatMessage:
+        """Read ``heartbeat`` from its body."""
+        return cls(timestamp=parse_timestamp(str(body["timestamp"])))
+
+
+@dataclass(frozen=True, slots=True)
+class SubInvokeMessage(ExecutorMessage):
+    """Executor to parent: run another published automation and send back its outcome."""
+
+    type_name: ClassVar[str] = "sub-invoke"
+
+    request_id: str
+    package_id: str
+    entry_point_id: str | None = None
+    inputs: Any | None = None
+    timeout_seconds: int | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``sub-invoke``."""
+        return omit_none(
+            {
+                "requestId": self.request_id,
+                "packageId": self.package_id,
+                "entryPointId": self.entry_point_id,
+                "inputs": self.inputs,
+                "timeoutSeconds": self.timeout_seconds,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> SubInvokeMessage:
+        """Read ``sub-invoke`` from its body."""
+        return cls(
+            request_id=str(body["requestId"]),
+            package_id=str(body["packageId"]),
+            entry_point_id=body.get("entryPointId"),
+            inputs=body.get("inputs"),
+            timeout_seconds=int(body["timeoutSeconds"]) if body.get("timeoutSeconds") is not None else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SubResultMessage(ExecutorMessage):
+    """Parent to executor: the outcome of a ``sub-invoke``."""
+
+    type_name: ClassVar[str] = "sub-result"
+
+    request_id: str
+    outcome: str
+    outputs: Any | None = None
+    fault: FaultInfo | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``sub-result``."""
+        return omit_none(
+            {
+                "requestId": self.request_id,
+                "outcome": self.outcome,
+                "outputs": self.outputs,
+                "fault": self.fault.to_json_value() if self.fault is not None else None,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> SubResultMessage:
+        """Read ``sub-result`` from its body."""
+        fault = body.get("fault")
+
+        return cls(
+            request_id=str(body["requestId"]),
+            outcome=str(body["outcome"]),
+            outputs=body.get("outputs"),
+            fault=FaultInfo.from_json_value(fault) if isinstance(fault, dict) else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugCommandMessage(ExecutorMessage):
+    """Parent to executor: a debugger command."""
+
+    type_name: ClassVar[str] = "debug-command"
+
+    command: str
+    breakpoints: list[BreakpointInfo] | None = None
+    expression: str | None = None
+    request_id: str | None = None
+    location: DebugLocation | None = None
+    reference: int | None = None
+    name: str | None = None
+    settings: DebugSettings | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``debug-command``."""
+        return omit_none(
+            {
+                "command": self.command,
+                "breakpoints": (
+                    [breakpoint.to_json_value() for breakpoint in self.breakpoints]
+                    if self.breakpoints is not None
+                    else None
+                ),
+                "expression": self.expression,
+                "requestId": self.request_id,
+                "location": self.location.to_json_value() if self.location is not None else None,
+                "reference": self.reference,
+                "name": self.name,
+                "settings": self.settings.to_json_value() if self.settings is not None else None,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugCommandMessage:
+        """Read ``debug-command`` from its body."""
+        breakpoints = body.get("breakpoints")
+
+        return cls(
+            command=str(body["command"]),
+            breakpoints=(
+                [BreakpointInfo.from_json_value(item) for item in breakpoints]
+                if isinstance(breakpoints, list)
+                else None
+            ),
+            expression=body.get("expression"),
+            request_id=body.get("requestId"),
+            location=_optional_location(body, "location"),
+            reference=_optional_int(body, "reference"),
+            name=body.get("name"),
+            settings=_optional_settings(body, "settings"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugPausedMessage(ExecutorMessage):
+    """Executor to parent: execution is paused at ``node_id``."""
+
+    type_name: ClassVar[str] = "debug-paused"
+
+    node_id: str
+    reason: str
+    locals: list[DebugVariableInfo] = field(default_factory=list)
+    call_stack: list[DebugFrameInfo] = field(default_factory=list)
+    workflow_path: str | None = None
+    exception: DebugExceptionInfo | None = None
+    previous_step: DebugStepOutputs | None = None
+    branch: str | None = None
+    """The parallel branch the run paused in (contracts 0.8.20, capability ``debug-branches``)."""
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``debug-paused``."""
+        return omit_none(
+            {
+                "nodeId": self.node_id,
+                "reason": self.reason,
+                "locals": [local.to_json_value() for local in self.locals],
+                "callStack": [frame.to_json_value() for frame in self.call_stack],
+                "workflowPath": self.workflow_path,
+                "exception": self.exception.to_json_value() if self.exception is not None else None,
+                "previousStep": self.previous_step.to_json_value() if self.previous_step is not None else None,
+                "branch": self.branch,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugPausedMessage:
+        """Read ``debug-paused`` from its body."""
+        exception = body.get("exception")
+        previous = body.get("previousStep")
+
+        return cls(
+            node_id=str(body["nodeId"]),
+            reason=str(body["reason"]),
+            locals=_variables(body, "locals"),
+            call_stack=[DebugFrameInfo.from_json_value(item) for item in body.get("callStack") or []],
+            workflow_path=body.get("workflowPath"),
+            exception=DebugExceptionInfo.from_json_value(exception) if isinstance(exception, dict) else None,
+            previous_step=DebugStepOutputs.from_json_value(previous) if isinstance(previous, dict) else None,
+            branch=body.get("branch"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugResumedMessage(ExecutorMessage):
+    """Executor to parent: execution continued."""
+
+    type_name: ClassVar[str] = "debug-resumed"
+
+    timestamp: datetime
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``debug-resumed``."""
+        return {"timestamp": format_timestamp(self.timestamp)}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugResumedMessage:
+        """Read ``debug-resumed`` from its body."""
+        return cls(timestamp=parse_timestamp(str(body["timestamp"])))
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluateResultMessage(ExecutorMessage):
+    """Executor to parent: the answer to an Evaluate command."""
+
+    type_name: ClassVar[str] = "evaluate-result"
+
+    request_id: str
+    succeeded: bool
+    value: str | None = None
+    type_name_of_value: str | None = None
+    error: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``evaluate-result``."""
+        return omit_none(
+            {
+                "requestId": self.request_id,
+                "succeeded": self.succeeded,
+                "value": self.value,
+                "typeName": self.type_name_of_value,
+                "error": self.error,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> EvaluateResultMessage:
+        """Read ``evaluate-result`` from its body."""
+        return cls(
+            request_id=str(body["requestId"]),
+            succeeded=bool(body["succeeded"]),
+            value=body.get("value"),
+            type_name_of_value=body.get("typeName"),
+            error=body.get("error"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugVariablesMessage(ExecutorMessage):
+    """Executor to parent: the children of an expandable variable (revision 1.1)."""
+
+    type_name: ClassVar[str] = "debug-variables"
+
+    request_id: str
+    reference: int
+    variables: list[DebugVariableInfo] = field(default_factory=list)
+    error: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``debug-variables``."""
+        return omit_none(
+            {
+                "requestId": self.request_id,
+                "reference": self.reference,
+                "variables": [variable.to_json_value() for variable in self.variables],
+                "error": self.error,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugVariablesMessage:
+        """Read ``debug-variables`` from its body."""
+        return cls(
+            request_id=str(body["requestId"]),
+            reference=int(body["reference"]),
+            variables=_variables(body, "variables"),
+            error=body.get("error"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugTraceMessage(ExecutorMessage):
+    """Executor to parent: an element started, completed, faulted or was skipped (revision 1.1)."""
+
+    type_name: ClassVar[str] = "debug-trace"
+
+    node_id: str
+    state: str
+    timestamp: datetime
+    display_name: str | None = None
+    workflow_path: str | None = None
+    kind: str | None = None
+    duration_milliseconds: int | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``debug-trace``."""
+        return omit_none(
+            {
+                "nodeId": self.node_id,
+                "displayName": self.display_name,
+                "state": self.state,
+                "timestamp": format_timestamp(self.timestamp),
+                "workflowPath": self.workflow_path,
+                "kind": self.kind,
+                "durationMilliseconds": self.duration_milliseconds,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugTraceMessage:
+        """Read ``debug-trace`` from its body."""
+        return cls(
+            node_id=str(body["nodeId"]),
+            state=str(body["state"]),
+            timestamp=parse_timestamp(str(body["timestamp"])),
+            display_name=body.get("displayName"),
+            workflow_path=body.get("workflowPath"),
+            kind=body.get("kind"),
+            duration_milliseconds=_optional_int(body, "durationMilliseconds"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DebugRestartedMessage(ExecutorMessage):
+    """Executor to parent: the run restarted from its first element (revision 1.1)."""
+
+    type_name: ClassVar[str] = "debug-restarted"
+
+    run: int
+    timestamp: datetime
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``debug-restarted``."""
+        return {"run": self.run, "timestamp": format_timestamp(self.timestamp)}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> DebugRestartedMessage:
+        """Read ``debug-restarted`` from its body."""
+        return cls(run=int(body["run"]), timestamp=parse_timestamp(str(body["timestamp"])))
+
+
+@dataclass(frozen=True, slots=True)
+class ResultMessage(ExecutorMessage):
+    """Executor to parent, terminal: the entry point completed."""
+
+    type_name: ClassVar[str] = "result"
+
+    outputs: Any | None = None
+    metrics: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``result``."""
+        return omit_none({"outputs": self.outputs, "metrics": self.metrics})
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> ResultMessage:
+        """Read ``result`` from its body."""
+        return cls(outputs=body.get("outputs"), metrics=body.get("metrics"))
+
+
+@dataclass(frozen=True, slots=True)
+class CanceledMessage(ExecutorMessage):
+    """Executor to parent, terminal: the run ended after a stop request."""
+
+    type_name: ClassVar[str] = "canceled"
+
+    reason: str
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``canceled``."""
+        return {"reason": self.reason}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> CanceledMessage:
+        """Read ``canceled`` from its body."""
+        return cls(reason=str(body["reason"]))
+
+
+@dataclass(frozen=True, slots=True)
+class FaultMessage(ExecutorMessage):
+    """Executor to parent, terminal (or the answer to a failed prepare): the run failed."""
+
+    type_name: ClassVar[str] = "fault"
+
+    fault: FaultInfo
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``fault``."""
+        return {"fault": self.fault.to_json_value()}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> FaultMessage:
+        """Read ``fault`` from its body."""
+        return cls(fault=FaultInfo.from_json_value(body["fault"]))
+
+
+# ------------------------------------------------------ durable execution (revision 2)
+#
+# The worker implements none of these: a Python automation is a function call and nothing in it
+# suspends, so it offers no revision 2 capability and a conformant parent never sends one. The
+# models exist anyway, because decoding is how the worker answers "unsupported" instead of
+# "malformed", and because the vectors are the protocol: a message the SDK cannot read is a
+# message the SDK cannot be checked against.
+
+
+class BookmarkKinds:
+    """Why a run is suspended. Mirrors the .NET ``BookmarkKinds``."""
+
+    TIMER: Final = "Timer"
+    HUMAN_TASK: Final = "HumanTask"
+    EVENT: Final = "Event"
+
+
+class RuntimeHealthStatuses:
+    """Values of ``RuntimeHealthReportMessage.status``."""
+
+    HEALTHY: Final = "Healthy"
+    DEGRADED: Final = "Degraded"
+    UNHEALTHY: Final = "Unhealthy"
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointInfo:
+    """A checkpoint, handed over as a file rather than as bytes on the wire.
+
+    A frame is capped at 16 MiB and a workflow's state is not, so the state stays in a file the
+    parent owns and only this descriptor crosses. See ``docs/CHECKPOINT-CONTRACT.md``.
+    """
+
+    checkpoint_id: str
+    path: str
+    digest: str
+    size_bytes: int
+    runtime_provider: str
+    runtime_provider_version: str
+    persistence_contract_version: int
+    package_digest: str
+    created_at: datetime
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``CheckpointInfo`` record."""
+        return {
+            "checkpointId": self.checkpoint_id,
+            "path": self.path,
+            "digest": self.digest,
+            "sizeBytes": self.size_bytes,
+            "runtimeProvider": self.runtime_provider,
+            "runtimeProviderVersion": self.runtime_provider_version,
+            "persistenceContractVersion": self.persistence_contract_version,
+            "packageDigest": self.package_digest,
+            "createdAt": format_timestamp(self.created_at),
+        }
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> CheckpointInfo:
+        """Read a checkpoint descriptor from its body."""
+        return cls(
+            checkpoint_id=str(body["checkpointId"]),
+            path=str(body["path"]),
+            digest=str(body["digest"]),
+            size_bytes=int(body["sizeBytes"]),
+            runtime_provider=str(body["runtimeProvider"]),
+            runtime_provider_version=str(body["runtimeProviderVersion"]),
+            persistence_contract_version=int(body["persistenceContractVersion"]),
+            package_digest=str(body["packageDigest"]),
+            created_at=parse_timestamp(body["createdAt"]),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BookmarkInfo:
+    """What a suspended run is waiting for. ``kind`` is one of ``BookmarkKinds``."""
+
+    name: str
+    kind: str
+    display_name: str | None = None
+    due_at: datetime | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``BookmarkInfo`` record."""
+        return omit_none(
+            {
+                "name": self.name,
+                "kind": self.kind,
+                "displayName": self.display_name,
+                "dueAt": _optional_timestamp(self.due_at),
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> BookmarkInfo:
+        """Read a bookmark from its body."""
+        due_at = body.get("dueAt")
+
+        return cls(
+            name=str(body["name"]),
+            kind=str(body["kind"]),
+            display_name=body.get("displayName"),
+            due_at=parse_timestamp(due_at) if due_at else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointMessage(ExecutorMessage):
+    """Parent to executor: write a checkpoint into ``checkpoint_root`` now."""
+
+    type_name: ClassVar[str] = "checkpoint"
+
+    checkpoint_root: str
+    reason: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``checkpoint``."""
+        return omit_none({"checkpointRoot": self.checkpoint_root, "reason": self.reason})
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> CheckpointMessage:
+        """Read ``checkpoint`` from its body."""
+        return cls(checkpoint_root=str(body["checkpointRoot"]), reason=body.get("reason"))
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointedMessage(ExecutorMessage):
+    """Executor to parent: a checkpoint was written and its digest verified by the writer."""
+
+    type_name: ClassVar[str] = "checkpointed"
+
+    checkpoint: CheckpointInfo
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``checkpointed``."""
+        return {"checkpoint": self.checkpoint.to_json_value()}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> CheckpointedMessage:
+        """Read ``checkpointed`` from its body."""
+        return cls(checkpoint=CheckpointInfo.from_json_value(body["checkpoint"]))
+
+
+@dataclass(frozen=True, slots=True)
+class RestoreMessage(ExecutorMessage):
+    """Parent to executor: run from a checkpoint instead of from the beginning.
+
+    A session carries ``start`` or ``restore``, never both.
+    """
+
+    type_name: ClassVar[str] = "restore"
+
+    package_root: str
+    checkpoint: CheckpointInfo
+    context: ExecutionContextInfo
+    environment_root: str | None = None
+    debug: DebugOptions | None = None
+    #: The tenant expression policy (engine ADR 0036), kept as read; Python has no expressions.
+    expression_policy: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``restore``."""
+        return omit_none(
+            {
+                "packageRoot": self.package_root,
+                "environmentRoot": self.environment_root,
+                "checkpoint": self.checkpoint.to_json_value(),
+                "context": self.context.to_json_value(),
+                "debug": self.debug.to_json_value() if self.debug is not None else None,
+                "expressionPolicy": self.expression_policy,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> RestoreMessage:
+        """Read ``restore`` from its body."""
+        debug = body.get("debug")
+
+        return cls(
+            package_root=str(body["packageRoot"]),
+            checkpoint=CheckpointInfo.from_json_value(body["checkpoint"]),
+            context=ExecutionContextInfo.from_json_value(body.get("context") or {}),
+            environment_root=body.get("environmentRoot"),
+            debug=DebugOptions.from_json_value(debug) if isinstance(debug, dict) else None,
+            expression_policy=body.get("expressionPolicy"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SuspendedMessage(ExecutorMessage):
+    """Executor to parent, terminal: the run suspended and can be resumed from the checkpoint."""
+
+    type_name: ClassVar[str] = "suspended"
+
+    checkpoint: CheckpointInfo
+    waiting: tuple[BookmarkInfo, ...] = ()
+    resume_at: datetime | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``suspended``."""
+        return omit_none(
+            {
+                "checkpoint": self.checkpoint.to_json_value(),
+                "waiting": [bookmark.to_json_value() for bookmark in self.waiting],
+                "resumeAt": _optional_timestamp(self.resume_at),
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> SuspendedMessage:
+        """Read ``suspended`` from its body."""
+        resume_at = body.get("resumeAt")
+
+        return cls(
+            checkpoint=CheckpointInfo.from_json_value(body["checkpoint"]),
+            waiting=tuple(BookmarkInfo.from_json_value(item) for item in body.get("waiting") or ()),
+            resume_at=parse_timestamp(resume_at) if resume_at else None,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ResumeBookmarkMessage(ExecutorMessage):
+    """Parent to executor: deliver a value to a waiting bookmark."""
+
+    type_name: ClassVar[str] = "resume-bookmark"
+
+    bookmark_name: str
+    value: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``resume-bookmark``."""
+        return omit_none({"bookmarkName": self.bookmark_name, "value": self.value})
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> ResumeBookmarkMessage:
+        """Read ``resume-bookmark`` from its body."""
+        return cls(bookmark_name=str(body["bookmarkName"]), value=body.get("value"))
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeHealthMessage(ExecutorMessage):
+    """Parent to executor: ask the runtime how it is."""
+
+    type_name: ClassVar[str] = "runtime-health"
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``runtime-health``. It carries nothing."""
+        return {}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> RuntimeHealthMessage:
+        """Read ``runtime-health`` from its body."""
+        return cls()
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeHealthReportMessage(ExecutorMessage):
+    """Executor to parent: the runtime's own view of its health."""
+
+    type_name: ClassVar[str] = "runtime-health-report"
+
+    status: str
+    detail: str | None = None
+    metrics: Any | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``runtime-health-report``."""
+        return omit_none({"status": self.status, "detail": self.detail, "metrics": self.metrics})
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> RuntimeHealthReportMessage:
+        """Read ``runtime-health-report`` from its body."""
+        return cls(
+            status=str(body["status"]),
+            detail=body.get("detail"),
+            metrics=body.get("metrics"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RequestStopMessage(ExecutorMessage):
+    """Parent to executor: ask the automation to end on its own (capability ``should-stop``).
+
+    It only raises the run's stop-requested flag (:func:`velophex.should_stop`); nothing is
+    canceled. Engine ADR 0037 section 6, contracts 0.8.16.
+    """
+
+    type_name: ClassVar[str] = "request-stop"
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``request-stop``. It carries nothing."""
+        return {}
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> RequestStopMessage:
+        """Read ``request-stop`` from its body."""
+        return cls()
+
+
+class TestOutcomes:
+    """Values of ``TestResultMessage.outcome`` and ``TestAssertionInfo.outcome`` (an open vocabulary)."""
+
+    PASSED: Final = "Passed"
+    FAILED: Final = "Failed"
+    ERROR: Final = "Error"
+    SKIPPED: Final = "Skipped"
+
+
+@dataclass(frozen=True, slots=True)
+class TestAssertionInfo:
+    """One verification a test case recorded (a Verify activity)."""
+
+    __test__ = False  # not a pytest test class
+
+    name: str
+    outcome: str
+    message: str | None = None
+    expected: str | None = None
+    actual: str | None = None
+    node_id: str | None = None
+    workflow_path: str | None = None
+    # Contracts 0.8.31: absolute path of the PNG a failed verification saved, on the machine that ran it.
+    screenshot_path: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of the .NET ``TestAssertionInfo`` record."""
+        return omit_none(
+            {
+                "name": self.name,
+                "outcome": self.outcome,
+                "message": self.message,
+                "expected": self.expected,
+                "actual": self.actual,
+                "nodeId": self.node_id,
+                "workflowPath": self.workflow_path,
+                "screenshotPath": self.screenshot_path,
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> TestAssertionInfo:
+        """Read an assertion from its body."""
+        return cls(
+            name=str(body["name"]),
+            outcome=str(body["outcome"]),
+            message=body.get("message"),
+            expected=body.get("expected"),
+            actual=body.get("actual"),
+            node_id=body.get("nodeId"),
+            workflow_path=body.get("workflowPath"),
+            screenshot_path=body.get("screenshotPath"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TestResultMessage(ExecutorMessage):
+    """Executor to parent: the outcome of one run (one data row) of a test case.
+
+    Capability ``test-results`` (contracts 0.8.25), which the parent opts in to. Not terminal.
+    """
+
+    __test__ = False  # not a pytest test class
+
+    type_name: ClassVar[str] = "test-result"
+
+    test_case_id: str
+    outcome: str
+    duration_milliseconds: int
+    assertions: tuple[TestAssertionInfo, ...] = ()
+    workflow_path: str | None = None
+    display_name: str | None = None
+    data_row_index: int | None = None
+    message: str | None = None
+    fault: FaultInfo | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered body of ``test-result``."""
+        return omit_none(
+            {
+                "testCaseId": self.test_case_id,
+                "outcome": self.outcome,
+                "durationMilliseconds": self.duration_milliseconds,
+                "assertions": [assertion.to_json_value() for assertion in self.assertions],
+                "workflowPath": self.workflow_path,
+                "displayName": self.display_name,
+                "dataRowIndex": self.data_row_index,
+                "message": self.message,
+                "fault": None if self.fault is None else self.fault.to_json_value(),
+            }
+        )
+
+    @classmethod
+    def from_json_value(cls, body: dict[str, Any]) -> TestResultMessage:
+        """Read ``test-result`` from its body."""
+        fault = body.get("fault")
+        row = body.get("dataRowIndex")
+
+        return cls(
+            test_case_id=str(body["testCaseId"]),
+            outcome=str(body["outcome"]),
+            duration_milliseconds=int(body["durationMilliseconds"]),
+            assertions=tuple(TestAssertionInfo.from_json_value(item) for item in body.get("assertions") or ()),
+            workflow_path=body.get("workflowPath"),
+            display_name=body.get("displayName"),
+            data_row_index=None if row is None else int(row),
+            message=body.get("message"),
+            fault=None if fault is None else FaultInfo.from_json_value(fault),
+        )
+
+
+_MESSAGE_TYPES: Final[dict[str, type[ExecutorMessage]]] = {
+    message.type_name: message
+    for message in (
+        HelloMessage,
+        HelloAckMessage,
+        PrepareMessage,
+        PreparedMessage,
+        StartMessage,
+        StopMessage,
+        LogMessage,
+        ProgressMessage,
+        HeartbeatMessage,
+        SubInvokeMessage,
+        SubResultMessage,
+        DebugCommandMessage,
+        DebugPausedMessage,
+        DebugResumedMessage,
+        EvaluateResultMessage,
+        DebugVariablesMessage,
+        DebugTraceMessage,
+        DebugRestartedMessage,
+        ResultMessage,
+        CanceledMessage,
+        FaultMessage,
+        # Revision 2: durable execution. The worker implements none of them; it decodes them so it
+        # can answer "unsupported" rather than killing the session as a protocol violation.
+        CheckpointMessage,
+        CheckpointedMessage,
+        RestoreMessage,
+        SuspendedMessage,
+        ResumeBookmarkMessage,
+        RuntimeHealthMessage,
+        RuntimeHealthReportMessage,
+        # Capability should-stop: the worker implements it.
+        RequestStopMessage,
+        # Capability test-results (contracts 0.8.25): the worker does not offer it, and decodes it
+        # only so the vectors round-trip.
+        TestResultMessage,
+    )
+}
+
+
+def message_type_name(message: ExecutorMessage) -> str:
+    """The ``type`` discriminator of *message*."""
+    return message.type_name
+
+
+def encode_message(message: ExecutorMessage) -> bytes:
+    """Serialize *message* as the UTF-8 envelope that becomes a frame payload."""
+    return _json.encode_wire({"type": message.type_name, "body": message.to_json_value()})
+
+
+def decode_message(payload: bytes) -> ExecutorMessage:
+    """Parse a frame payload. Unknown types and malformed JSON are protocol violations."""
+    try:
+        envelope = _json.loads(payload)
+    except ValueError as error:
+        raise ExecutorProtocolException(
+            ExecutorProtocolError.MALFORMED_MESSAGE, "The frame payload is not valid JSON."
+        ) from error
+
+    if (
+        not isinstance(envelope, dict)
+        or not isinstance(envelope.get("type"), str)
+        or not isinstance(envelope.get("body"), dict)
+    ):
+        raise ExecutorProtocolException(
+            ExecutorProtocolError.MALFORMED_MESSAGE, "The frame payload is not a message envelope."
+        )
+
+    name = envelope["type"]
+    message_type = _MESSAGE_TYPES.get(name)
+
+    if message_type is None:
+        raise ExecutorProtocolException(
+            ExecutorProtocolError.UNKNOWN_MESSAGE_TYPE, f"Unknown message type '{_printable(name)}'."
+        )
+
+    try:
+        return message_type.from_json_value(envelope["body"])
+    except NotImplementedError:
+        raise ExecutorProtocolException(
+            ExecutorProtocolError.UNKNOWN_MESSAGE_TYPE, f"A '{name}' message is never sent to this side."
+        ) from None
+    except (KeyError, TypeError, ValueError) as error:
+        raise ExecutorProtocolException(
+            ExecutorProtocolError.MALFORMED_MESSAGE, f"The '{name}' message body is malformed."
+        ) from error
+
+
+def _printable(value: str) -> str:
+    return "".join(character if character.isprintable() else "?" for character in value[:64])
+
+
+def select_version(offered_minimum: int, offered_maximum: int) -> int | None:
+    """The highest version both sides speak, or ``None`` when the ranges do not overlap."""
+    if offered_minimum < 1 or offered_maximum < offered_minimum:
+        return None
+
+    highest = min(offered_maximum, CURRENT_VERSION)
+    lowest = max(offered_minimum, MINIMUM_VERSION)
+
+    return highest if highest >= lowest else None