loop-sdk 0.1.0__py3-none-any.whl

loop_sdk/source/outbound/grpc_source_client.py

@@ -0,0 +1,360 @@
+"""gRPC implementation of the source client (synchronous + background threads).
+
+Threading model (see ``docs/spec_discrepancies.md`` items 3, 12, 14):
+
+* A **supervisor** thread owns the connect/reconnect loop. Each iteration runs
+  one session and, on transport failure, backs off and reconnects (re-sending
+  ``ClientReady`` and re-answering ``Describe``).
+* Within a session, the **control** plane runs on the supervisor thread itself:
+  it sends ``ClientEvent``s from an outbound event queue and reads
+  ``RecorderCommand``s, answering ``Describe`` from the cached schema and acting
+  on ``Open`` / ``Close`` / ``Shutdown``. The first ``Open`` records the session
+  id and unblocks the sender; ``Close`` stops the sender for that session while
+  leaving the control connection up; ``Shutdown`` tears the connection down.
+* A **sender** thread runs ``StreamSamples``, draining the frame queue and
+  mapping each frame to a one-sample ``SampleBatch``. It starts once the Source Bus
+  opens the session and retires on ``Close`` or disconnect.
+
+``submit()`` only touches the lock-free-ish bounded queue, so the customer's
+control loop never blocks on the network. Transport failures are translated into
+domain ``SourceError`` subclasses at this boundary.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from collections.abc import Iterator
+
+import grpc
+
+from loop_sdk.gen.v1 import source_ingest_pb2 as pb2
+from loop_sdk.gen.v1 import source_ingest_pb2_grpc as pb2_grpc
+from loop_sdk.source.domain.config import OnSelectRobotConfig, RobotConfig
+from loop_sdk.source.domain.frame import FrameSample
+from loop_sdk.source.domain.schema import SourceSchema
+from loop_sdk.source.domain.source_exception import NotConnectedError
+from loop_sdk.source.domain.stats import SendStats
+from loop_sdk.source.outbound import proto_mapping
+from loop_sdk.source.outbound.frame_queue import FrameQueue
+from loop_sdk.source.port.source_client import SourceClient
+
+# gRPC keepalive so a silent half-open connection is detected and recycled.
+_CHANNEL_OPTIONS = (
+    ("grpc.keepalive_time_ms", 10_000),
+    ("grpc.keepalive_timeout_ms", 5_000),
+    ("grpc.keepalive_permit_without_calls", 1),
+)
+
+
+class _Stats:
+    """Mutable, lock-guarded counters projected into the immutable ``SendStats``."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.enqueued = 0
+        self.sent = 0
+        self.failed = 0
+        self.reconnects = 0
+        self.connected = False
+
+    def snapshot(self, dropped: int) -> SendStats:
+        with self._lock:
+            return SendStats(
+                enqueued=self.enqueued,
+                sent=self.sent,
+                failed=self.failed,
+                dropped=dropped,
+                reconnects=self.reconnects,
+                connected=self.connected,
+            )
+
+    def incr(self, field: str, by: int = 1) -> None:
+        with self._lock:
+            setattr(self, field, getattr(self, field) + by)
+
+    def set_connected(self, value: bool) -> None:
+        with self._lock:
+            self.connected = value
+
+
+class GrpcSourceClient(SourceClient):
+    """Drive one Source Bus connection over synchronous gRPC with background threads."""
+
+    def __init__(
+        self,
+        loop_addr: str,
+        client_id: str,
+        version: str,
+        reconnect_backoff_seconds: float,
+        reconnect_backoff_max_seconds: float,
+        on_select: OnSelectRobotConfig | None,
+    ) -> None:
+        self._loop_addr = loop_addr
+        self._client_id = client_id
+        self._version = version
+        self._reconnect_backoff_seconds = reconnect_backoff_seconds
+        self._reconnect_backoff_max_seconds = reconnect_backoff_max_seconds
+        self._on_select = on_select
+
+        self._schema: SourceSchema | None = None
+        self._frames = FrameQueue()
+        self._stats = _Stats()
+        self._closed = threading.Event()
+        self._supervisor: threading.Thread | None = None
+        # The in-flight Connect call, cancelled on shutdown/close to unblock the
+        # response iterator (closing only the request side does not end it).
+        self._active_call: grpc.Call | None = None
+
+        # Per-session state, reset on each (re)connect.
+        self._events: queue.SimpleQueue[pb2.ClientEvent | None] = queue.SimpleQueue()
+        self._opened = False
+        self._session_id = ""
+        self._session_ready = threading.Event()
+        self._session_ended = threading.Event()
+
+    # -- SourceClient contract -------------------------------------------------
+
+    def start(self, schema: SourceSchema) -> None:
+        self._schema = schema
+        self._supervisor = threading.Thread(target=self._supervise, name="source-supervisor", daemon=True)
+        self._supervisor.start()
+
+    def submit(self, frame: FrameSample) -> None:
+        if self._schema is None:
+            raise NotConnectedError("start() must be called before submit()")
+        self._stats.incr("enqueued")
+        self._frames.put(frame)
+
+    def report_error(self, source_id: str, code: str, message: str = "") -> None:
+        # Queue a control-plane ClientError; the server turns it into a per-source
+        # SourceEvent(FAILED). Best-effort: if no session is live the event rides
+        # the next connection or is dropped on reset. Never blocks the caller.
+        if self._schema is None:
+            raise NotConnectedError("start() must be called before report_error()")
+        self._events.put(_error_event(self._client_id, source_id, code, message))
+
+    def stats(self) -> SendStats:
+        return self._stats.snapshot(self._frames.dropped)
+
+    def close(self) -> None:
+        self._closed.set()
+        self._frames.close()
+        self._events.put(None)
+        self._cancel_active_call()
+        supervisor = self._supervisor
+        if supervisor is not None:
+            supervisor.join(timeout=5.0)
+
+    # -- supervisor / reconnect loop --------------------------------------------
+
+    def _supervise(self) -> None:
+        backoff = self._reconnect_backoff_seconds
+        first_attempt = True
+        while not self._closed.is_set():
+            if not first_attempt:
+                self._stats.incr("reconnects")
+            first_attempt = False
+            reached_live = self._run_session()
+            if self._closed.is_set():
+                return
+            if reached_live:
+                backoff = self._reconnect_backoff_seconds
+            self._sleep_backoff(backoff)
+            backoff = min(backoff * 2, self._reconnect_backoff_max_seconds)
+
+    def _run_session(self) -> bool:
+        """Run one connection. Return whether it reached a live (post-ready) state.
+
+        "Live" means the server actually answered (the first ``RecorderCommand``
+        arrived), not merely that the channel opened — a connection that opens
+        and instantly drops must NOT reset the reconnect backoff.
+        """
+        self._reset_session()
+        sender: threading.Thread | None = None
+        reached_live = False
+        try:
+            channel = grpc.insecure_channel(self._loop_addr, options=_CHANNEL_OPTIONS)
+            with channel:
+                stub = pb2_grpc.SourceIngestServiceStub(channel)
+                self._events.put(_ready_event(self._client_id, self._version))
+                sender = threading.Thread(target=self._run_sender, args=(stub,), name="source-sender", daemon=True)
+                sender.start()
+                call = stub.Connect(self._drain_events())
+                self._active_call = call
+                self._stats.set_connected(True)
+                for command in call:
+                    reached_live = True
+                    self._handle_command(command)
+        except grpc.RpcError:
+            pass
+        finally:
+            self._active_call = None
+            self._stats.set_connected(False)
+            self._end_session(sender)
+        return reached_live
+
+    def _reset_session(self) -> None:
+        self._events = queue.SimpleQueue()
+        self._opened = False
+        self._session_id = ""
+        self._session_ready.clear()
+        self._session_ended.clear()
+        self._frames.reset_wake()
+
+    def _end_session(self, sender: threading.Thread | None) -> None:
+        # Unblock the sender's StreamSamples iterator so the thread can exit
+        # without closing the shared frame queue (which survives reconnects).
+        self._session_ended.set()
+        self._session_ready.set()
+        self._events.put(None)
+        self._frames.wake()
+        if sender is not None:
+            sender.join(timeout=2.0)
+
+    def _sleep_backoff(self, seconds: float) -> None:
+        # Wait, but wake immediately if close() is called.
+        self._closed.wait(timeout=seconds)
+
+    def _cancel_active_call(self) -> None:
+        # Cancel the in-flight Connect so the response iterator unblocks. Safe to
+        # call when there is no active call or it has already finished.
+        call = self._active_call
+        if call is None:
+            return
+        call.cancel()
+
+    # -- control plane ----------------------------------------------------------
+
+    def _drain_events(self) -> Iterator[pb2.ClientEvent]:
+        while True:
+            event = self._events.get()
+            if event is None:
+                return
+            yield event
+
+    def _handle_command(self, command: pb2.RecorderCommand) -> None:
+        which = command.WhichOneof("command")
+        if which == "describe":
+            self._answer_describe(command.command_id)
+            return
+        if which == "open":
+            self._handle_open(command.open)
+            return
+        if which == "close":
+            self._handle_close(command.close)
+            return
+        if which == "shutdown":
+            self._events.put(None)
+            self._cancel_active_call()
+            return
+
+    def _answer_describe(self, command_id: str) -> None:
+        assert self._schema is not None
+        discovered = proto_mapping.discovered_events(self._schema)
+        for message in discovered:
+            event = pb2.ClientEvent(client_id=self._client_id, command_id=command_id)
+            event.source_discovered.CopyFrom(message)
+            self._events.put(event)
+        completed = pb2.ClientEvent(client_id=self._client_id, command_id=command_id)
+        completed.scan_completed.CopyFrom(pb2.ScanCompleted(discovered_count=len(discovered)))
+        self._events.put(completed)
+
+    def _handle_open(self, open_command: pb2.OpenCommand) -> None:
+        # A client may receive several open commands (one per source), each
+        # possibly carrying a negotiated robot config to apply — so negotiate on
+        # every open, not just the first.
+        self._apply_robot_config(open_command)
+        # Open unblocks the data-plane sender. The Source Bus identifies the
+        # opened source(s) via ``source_ids``; ``session_id`` is an optional tag
+        # the bus may leave empty (it routes batches by source_id), so it must
+        # NOT gate streaming. The operator drives recording start/stop.
+        if self._opened:
+            return
+        self._opened = True
+        self._session_id = open_command.session_id
+        self._session_ready.set()
+
+    def _apply_robot_config(self, open_command: pb2.OpenCommand) -> None:
+        if open_command.WhichOneof("params") != "robot":
+            return
+        if not open_command.robot.HasField("requested_config"):
+            return
+        requested = proto_mapping.robot_config_from_pb(open_command.robot.requested_config)
+        for source_id in open_command.source_ids:
+            self._negotiate_source(open_command.session_id, source_id, requested)
+
+    def _negotiate_source(self, session_id: str, source_id: str, requested: RobotConfig) -> None:
+        if self._on_select is None:
+            # The server selected a config but the client gave no apply callback;
+            # it cannot honor the request. Report FAILED and let the server decide.
+            self._events.put(
+                _failed_event(self._client_id, session_id, source_id, "no on_select callback to apply robot config")
+            )
+            return
+        try:
+            applied = self._on_select(source_id, requested)
+        except Exception as error:  # user callback: any failure means the source cannot open
+            self._events.put(_failed_event(self._client_id, session_id, source_id, str(error)))
+            return
+        self._events.put(_applied_event(self._client_id, session_id, source_id, applied or requested))
+
+    def _handle_close(self, close_command: pb2.Close) -> None:
+        # The Source Bus ended the session's data stream. Stop the sender (end the
+        # StreamSamples iterator) but keep the Connect control stream up so the
+        # server can re-scan or shut down cleanly. The frame queue survives.
+        if close_command.session_id and close_command.session_id != self._session_id:
+            return
+        self._session_ended.set()
+        self._session_ready.set()
+        self._frames.wake()
+
+    # -- data plane -------------------------------------------------------------
+
+    def _run_sender(self, stub: pb2_grpc.SourceIngestServiceStub) -> None:
+        # Wait until the Source Bus has opened the source(s) (or the session ended).
+        self._session_ready.wait()
+        if not self._opened or self._closed.is_set():
+            return
+        try:
+            stub.StreamSamples(self._drain_batches(self._session_id))
+        except grpc.RpcError:
+            self._stats.incr("failed")
+
+    def _drain_batches(self, session_id: str) -> Iterator[pb2.SampleBatch]:
+        while not self._session_ended.is_set():
+            frame = self._frames.get()
+            if frame is None:
+                return
+            yield proto_mapping.sample_batch(frame, session_id)
+            self._stats.incr("sent")
+
+
+def _ready_event(client_id: str, version: str) -> pb2.ClientEvent:
+    event = pb2.ClientEvent(client_id=client_id)
+    event.ready.CopyFrom(pb2.ClientReady(version=version))
+    return event
+
+
+def _error_event(client_id: str, source_id: str, code: str, message: str) -> pb2.ClientEvent:
+    event = pb2.ClientEvent(client_id=client_id)
+    event.error.CopyFrom(pb2.ClientError(code=code, message=message, source_id=source_id))
+    return event
+
+
+def _applied_event(client_id: str, session_id: str, source_id: str, applied: RobotConfig) -> pb2.ClientEvent:
+    event = pb2.ClientEvent(client_id=client_id)
+    changed = pb2.StreamStateChanged(session_id=session_id, source_id=source_id, state=pb2.STREAM_STATE_STARTED)
+    changed.robot.CopyFrom(proto_mapping.robot_config_to_pb(applied))
+    event.stream_state_changed.CopyFrom(changed)
+    return event
+
+
+def _failed_event(client_id: str, session_id: str, source_id: str, detail: str) -> pb2.ClientEvent:
+    event = pb2.ClientEvent(client_id=client_id)
+    event.stream_state_changed.CopyFrom(
+        pb2.StreamStateChanged(
+            session_id=session_id, source_id=source_id, state=pb2.STREAM_STATE_FAILED, detail=detail
+        )
+    )
+    return event

loop_sdk/source/outbound/grpc_source_reader.py

@@ -0,0 +1,82 @@
+"""gRPC implementation of the source reader (synchronous, blocking iterator).
+
+The mirror of ``GrpcSourceClient``: where the producer drives ``StreamSamples``
+(client -> server), the consumer drives ``SourceReadService.Subscribe`` (server
+-> client). A subscription is a single server-streaming call, so it maps cleanly
+to a blocking Python iterator — no background threads are needed.
+
+``close()`` cancels the in-flight call from another thread so a consumer blocked
+in the ``for frame in ...:`` loop unblocks promptly. Transport failures and
+per-source faults are translated into domain ``SourceError`` subclasses at this
+boundary.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+
+import grpc
+
+from loop_sdk.gen.v1 import source_ingest_pb2 as pb2
+from loop_sdk.gen.v1 import source_ingest_pb2_grpc as pb2_grpc
+from loop_sdk.source.domain.frame import FrameSample
+from loop_sdk.source.domain.source_exception import SubscriptionFailedError
+from loop_sdk.source.outbound import proto_mapping
+from loop_sdk.source.port.source_reader import SourceReader
+
+# gRPC keepalive so a silent half-open connection is detected and recycled.
+_CHANNEL_OPTIONS = (
+    ("grpc.keepalive_time_ms", 10_000),
+    ("grpc.keepalive_timeout_ms", 5_000),
+    ("grpc.keepalive_permit_without_calls", 1),
+)
+
+
+class GrpcSourceReader(SourceReader):
+    """Read one source's samples over synchronous gRPC server-streaming."""
+
+    def __init__(self, loop_addr: str) -> None:
+        self._channel = grpc.insecure_channel(loop_addr, options=_CHANNEL_OPTIONS)
+        self._stub = pb2_grpc.SourceReadServiceStub(self._channel)
+        self._closed = threading.Event()
+        self._active_call: grpc.Call | None = None
+
+    def subscribe(self, source_id: str, session_id: str = "") -> Iterator[FrameSample]:
+        request = pb2.SubscribeRequest(source_id=source_id, session_id=session_id)
+        call = self._stub.Subscribe(request)
+        self._active_call = call
+        try:
+            yield from self._drain(source_id, call)
+        except grpc.RpcError as error:
+            if self._closed.is_set() or error.code() == grpc.StatusCode.CANCELLED:
+                return
+            raise SubscriptionFailedError(source_id, _rpc_detail(error)) from error
+        finally:
+            self._active_call = None
+
+    def _drain(self, source_id: str, call: Iterator[pb2.SubscribeEvent]) -> Iterator[FrameSample]:
+        for event in call:
+            which = event.WhichOneof("event")
+            if which == "sample":
+                yield proto_mapping.frame_from_sample(source_id, event.sample)
+                continue
+            if which == "state":
+                # STARTED/UNSPECIFIED are informational; STOPPED ends the stream
+                # cleanly; FAILED surfaces the per-source fault to the caller.
+                if event.state.state == pb2.STREAM_STATE_STOPPED:
+                    return
+                if event.state.state == pb2.STREAM_STATE_FAILED:
+                    raise SubscriptionFailedError(source_id, event.state.detail)
+
+    def close(self) -> None:
+        self._closed.set()
+        call = self._active_call
+        if call is not None:
+            call.cancel()
+        self._channel.close()
+
+
+def _rpc_detail(error: grpc.RpcError) -> str:
+    code = error.code()
+    return code.name if code is not None else "transport error"

loop_sdk/source/outbound/proto_mapping.py

@@ -0,0 +1,239 @@
+"""Protobuf <-> domain mapping for the Source Bus contract.
+
+Lives in ``outbound/`` because it touches generated stubs. The rest of the SDK
+(domain, service, port) never imports ``pb2``.
+"""
+
+from __future__ import annotations
+
+from loop_sdk.gen.v1 import source_ingest_pb2 as pb2
+from loop_sdk.source.domain.config import RobotConfig, RobotConfigOptions
+from loop_sdk.source.domain.frame import (
+    FrameSample,
+    MarkerFrame,
+    PolicyActionFrame,
+    RobotFrame,
+    RobotStateValue,
+    TactileChannelValue,
+    TactileFrame,
+)
+from loop_sdk.source.domain.schema import (
+    ChannelRole,
+    ChannelSpec,
+    MarkerStreamSchema,
+    RobotStreamSchema,
+    RotationType,
+    SourceSchema,
+    TactileStreamSchema,
+)
+
+# Domain closed-enum -> proto enum. None/omitted maps to the proto's UNSPECIFIED.
+_ROLE_TO_PB = {
+    ChannelRole.CORE: pb2.CHANNEL_ROLE_CORE,
+    ChannelRole.AUX: pb2.CHANNEL_ROLE_AUX,
+}
+_ROT_TO_PB = {
+    RotationType.QUATERNION: pb2.ROBOT_ROTATION_TYPE_QUATERNION,
+    RotationType.EULER: pb2.ROBOT_ROTATION_TYPE_EULER,
+    RotationType.ROTATION_6D: pb2.ROBOT_ROTATION_TYPE_ROTATION_6D,
+}
+
+
+def discovered_events(schema: SourceSchema) -> list[pb2.SourceDiscovered]:
+    """Build the ``SourceDiscovered`` messages that answer a ``Describe``."""
+    events: list[pb2.SourceDiscovered] = []
+    events.extend(_robot_discovered(stream) for stream in schema.robot)
+    events.extend(_tactile_discovered(stream) for stream in schema.tactile)
+    events.extend(_marker_discovered(stream) for stream in schema.marker)
+    return events
+
+
+def _robot_channel(channel: ChannelSpec) -> pb2.RobotChannelDescriptor:
+    descriptor = pb2.RobotChannelDescriptor(
+        key=channel.key, label=channel.label, unit=channel.unit, group=channel.group
+    )
+    if channel.role is not None:
+        descriptor.role = _ROLE_TO_PB[channel.role]
+    if channel.rot_type is not None:
+        descriptor.rot_type = _ROT_TO_PB[channel.rot_type]
+    if channel.range is not None:
+        descriptor.range.extend(channel.range)
+    return descriptor
+
+
+def _robot_discovered(stream: RobotStreamSchema) -> pb2.SourceDiscovered:
+    message = pb2.SourceDiscovered(source_id=stream.source_id, name=stream.name)
+    message.robot.channels.extend(_robot_channel(channel) for channel in stream.channels)
+    message.robot.available_options.CopyFrom(_robot_config_options(stream.available_options))
+    return message
+
+
+def _robot_config_options(options: RobotConfigOptions) -> pb2.RobotConfigOptions:
+    return pb2.RobotConfigOptions(
+        control_hz=options.control_hz,
+        action_space=options.action_space,
+        gripper_type=options.gripper_type,
+        finger_type=options.finger_type,
+        robot_type=options.robot_type,
+        robot_firmware_version=options.robot_firmware_version,
+        teleoperation_version=options.teleoperation_version,
+    )
+
+
+def robot_config_to_pb(config: RobotConfig) -> pb2.RobotConfig:
+    # control_hz/action_space are always set; the optional identity fields are
+    # set only when non-empty so an unset proto `optional` stays absent.
+    message = pb2.RobotConfig(control_hz=config.control_hz, action_space=config.action_space)
+    if config.gripper_type:
+        message.gripper_type = config.gripper_type
+    if config.finger_type:
+        message.finger_type = config.finger_type
+    if config.robot_type:
+        message.robot_type = config.robot_type
+    if config.robot_firmware_version:
+        message.robot_firmware_version = config.robot_firmware_version
+    if config.teleoperation_version:
+        message.teleoperation_version = config.teleoperation_version
+    return message
+
+
+def robot_config_from_pb(message: pb2.RobotConfig) -> RobotConfig:
+    # Unset proto `optional string` reads back as "" — the domain default.
+    return RobotConfig(
+        control_hz=message.control_hz,
+        action_space=message.action_space,
+        gripper_type=message.gripper_type,
+        finger_type=message.finger_type,
+        robot_type=message.robot_type,
+        robot_firmware_version=message.robot_firmware_version,
+        teleoperation_version=message.teleoperation_version,
+    )
+
+
+def _tactile_discovered(stream: TactileStreamSchema) -> pb2.SourceDiscovered:
+    message = pb2.SourceDiscovered(source_id=stream.source_id, name=stream.name)
+    message.tactile.channels.extend(
+        pb2.TactileChannelDescriptor(
+            key=channel.key,
+            label=channel.label,
+            sample_format=channel.sample_format,
+            sample_count=channel.sample_count,
+        )
+        for channel in stream.channels
+    )
+    return message
+
+
+def _marker_discovered(stream: MarkerStreamSchema) -> pb2.SourceDiscovered:
+    message = pb2.SourceDiscovered(source_id=stream.source_id, name=stream.name)
+    message.marker.CopyFrom(pb2.MarkerSourceDescriptor())
+    return message
+
+
+def sample_batch(frame: FrameSample, session_id: str) -> pb2.SampleBatch:
+    """Map one domain frame to a single-sample ``SampleBatch``."""
+    return pb2.SampleBatch(
+        session_id=session_id,
+        source_id=frame.source_id,
+        samples=[_sample(frame)],
+    )
+
+
+def _to_pb_robot_value(value: RobotStateValue) -> pb2.RobotValue:
+    # bool is a subclass of int, so it must be checked first. None / unknown
+    # types yield an empty RobotValue (no arm set) and are filtered before this.
+    if isinstance(value, bool):
+        return pb2.RobotValue(bool_value=value)
+    if isinstance(value, int):
+        return pb2.RobotValue(int_value=value)
+    if isinstance(value, float):
+        return pb2.RobotValue(scalar=value)
+    if isinstance(value, str):
+        return pb2.RobotValue(string_value=value)
+    if isinstance(value, list):
+        return pb2.RobotValue(array=pb2.DoubleArray(values=[float(item) for item in value]))
+    return pb2.RobotValue()
+
+
+def _robot_state_value(value: pb2.RobotValue) -> RobotStateValue:
+    arm = value.WhichOneof("value")
+    if arm == "scalar":
+        return value.scalar
+    if arm == "array":
+        return list(value.array.values)
+    if arm == "int_value":
+        return value.int_value
+    if arm == "bool_value":
+        return value.bool_value
+    if arm == "string_value":
+        return value.string_value
+    return None
+
+
+def _sample(frame: FrameSample) -> pb2.Sample:
+    sample = pb2.Sample(timestamp_us=frame.timestamp_us, sequence=frame.sequence)
+    if isinstance(frame, RobotFrame):
+        for key, value in frame.state.items():
+            if value is None:
+                continue
+            sample.robot.state[key].CopyFrom(_to_pb_robot_value(value))
+        return sample
+    if isinstance(frame, TactileFrame):
+        sample.tactile.channels.extend(
+            pb2.TactileChannelSample(key=channel.key, raw=channel.raw, values_i16=channel.values_i16)
+            for channel in frame.channels
+        )
+        return sample
+    if isinstance(frame, MarkerFrame):
+        sample.marker.CopyFrom(pb2.MarkerPayload(label=frame.label, category=frame.category))
+        return sample
+    raise TypeError(f"unsupported frame type: {type(frame).__name__}")
+
+
+def frame_from_sample(source_id: str, sample: pb2.Sample) -> FrameSample:
+    """Decode one read-plane ``Sample`` into a domain frame (the inverse of ``_sample``).
+
+    ``Sample`` carries no ``source_id`` (it is per-source on the wire); the
+    subscription supplies it.
+    """
+    payload = sample.WhichOneof("payload")
+    if payload == "robot":
+        return RobotFrame(
+            source_id=source_id,
+            timestamp_us=sample.timestamp_us,
+            sequence=sample.sequence,
+            state={key: _robot_state_value(value) for key, value in sample.robot.state.items()},
+        )
+    if payload == "tactile":
+        return TactileFrame(
+            source_id=source_id,
+            timestamp_us=sample.timestamp_us,
+            sequence=sample.sequence,
+            channels=tuple(
+                TactileChannelValue(key=channel.key, raw=channel.raw, values_i16=tuple(channel.values_i16))
+                for channel in sample.tactile.channels
+            ),
+        )
+    if payload == "marker":
+        return MarkerFrame(
+            source_id=source_id,
+            timestamp_us=sample.timestamp_us,
+            sequence=sample.sequence,
+            label=sample.marker.label,
+            category=sample.marker.category,
+        )
+    if payload == "policy_action":
+        pa = sample.policy_action
+        return PolicyActionFrame(
+            source_id=source_id,
+            timestamp_us=sample.timestamp_us,
+            sequence=sample.sequence,
+            actions=tuple(tuple(vector.values) for vector in pa.actions),
+            input_sample_set_source_id=(
+                pa.input_sample_set_source_id if pa.HasField("input_sample_set_source_id") else None
+            ),
+            input_sample_set_sequence=(
+                pa.input_sample_set_sequence if pa.HasField("input_sample_set_sequence") else None
+            ),
+        )
+    raise TypeError(f"sample carries no known payload (oneof={payload!r})")