plesty-lib 0.3.5.dev2__tar.gz → 0.3.5.dev3__tar.gz

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.3.5.dev3 — 2026-08-18
+
+Development pre-release for field-testing operation kinds (#39): operations
+declare what they do and the field test drives a motion out and back, a
+lifecycle op once, a control op at rest; plus the pol-pl rig findings #35
+and #38. Same line as 0.3.5.dev2 — the final release is 0.4.0.
+
+- **Operations declare what they do, and the field test drives them by
+  kind** (#39). `@expose_to_api(kind=…)` and a schema `kind` block record
+  one of `read | motion | acquire | lifecycle | control | configure`
+  (`plesty.lib.device.device_utils.OpKind`; `FuncDoc.kind`, the describe
+  payload and `function_docs()` carry it). `FieldTestPipeline` acts on it
+  instead of asking the developer per operation: a `motion` op is driven
+  one `step` out from what its `position_key` reports and put back (the
+  functions gate checks it came back; the stability gate repeats out and
+  back), a `lifecycle` op runs once when allow-listed and never on repeat,
+  a `control` op once at rest after the motions (skipped when nothing
+  moved), a `configure` op is never called. `op_kinds={…}` overrides the
+  module's declaration. On plesty-k10cr1 the operation every pol-pl row
+  calls could not be tested at all: `move_absolute(position)` was called
+  bare and failed on the missing argument.
+- **The client tier drives operations by kind too.** `ClientFieldTest`
+  takes `op_kinds=` (the generated `field_test_client.py` passes the host
+  tier's): a motion is queried through `position_key`, moved one step out
+  and back over the wire as many pairs as the host tier's call count, a
+  lifecycle op once, a control op once after the motions, a configure op
+  never; a motion without `position_key`/`target`/`step` fails the gate.
+- **A provocation that breaks is a failed gate, not a forced timeout.**
+  The drain and recovery gates called the slow op with the payload as one
+  positional dict (`getattr(device, slow_op)(dict(payload))`), so an
+  `@expose_to_api` slow op raised `TypeError` before any transport
+  traffic — and both gates counted the exception as an abandoned call and
+  passed. The call now goes through the operation's own call form, only a
+  timeout-class error counts as forced, and a motion slow op is a delta
+  from where the part is, moved back afterwards (`motion_restored` in the
+  evidence). The slow-op payload is prepared before the timeout is
+  shortened, so reading the start position cannot itself time out.
+
+- **A serial port that is held says so** (#35). pyserial reports a wrong
+  port name and a port open in another process with the same
+  `SerialException`, and on the K10CR1 rig `Access is denied` on the right
+  `COM4` — Kinesis had the stage loaded — cost the session to driver and
+  VCP checks. `TrafficManager.open` now asks the subclass to explain a
+  failure (`_explain_open_error`, `None` by default) and appends the answer
+  to the raised message. `AptTrafficManager` and `SerialTrafficManager`
+  answer for EACCES/EBUSY: on Windows and for EBUSY, the port exists but is
+  open elsewhere — close Kinesis/APT (a loaded stage locks the FTDI device
+  via D2XX and blocks the VCP), stray interpreters, serial terminals, replug
+  to drop a stale handle; on Linux EACCES, add the user to `dialout`. The
+  port's `list_ports` description and hwid follow, so the user sees at once
+  whether the address is the intended device. Windows sets no `errno` on
+  the exception, so the number is read out of the message text. Other
+  failures (`ENOENT`, timeouts) are reported as before.
+- `ModuleInfo.from_project` and the field-test version lookup no longer
+  answer for whatever repository `GIT_DIR` names: a git hook exports it for
+  the repository being pushed, and every `git -C <root>` in `report_artifact`
+  followed it — a field test run from a pre-push hook reported the hook's
+  remote and version, and the pre-push suite failed on the tmp-dir module
+  test. `GIT_*` is scrubbed from the subprocess environment.
+
+- **Client-tier `functions` gate no longer demands a dict of every
+  operation** (#38). It required `isinstance(answer, dict)` for each
+  allow-listed operation, while the host tier asks that only of
+  schema-declared ones; on lightfield_spectrometer `acquire` (`None`) and
+  `get_recent_file` (`str`) came back 21 times each with no failure and
+  the gate still failed. A call that returns is the pass; the answer's
+  type is recorded in the evidence.
+
 ## 0.3.5.dev2 — 2026-08-17
 
 Development pre-release for field-testing the rig start-up (#36, #37):

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-lib
-Version: 0.3.5.dev2
+Version: 0.3.5.dev3
 Summary: A library for the Plesty ecosystem.
 Author: Plesty Development Team
 Author-email: Yunshuang Yuan <yunshuang.yuan@fkp.uni-hannover.de>

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/docs/device/base_device.md

@@ -261,7 +261,12 @@ model.standard_methods   # the common device API (connect/write/query/reset/...)
 `functions` unifies the two ways a device gains operations: schema-registered
 operations (`source="schema"`) and `@expose_to_api` methods
 (`source="custom"`); framework plumbing is kept out and surfaced separately
-under `standard_methods` (`source="standard"`). Per-parameter and return
+under `standard_methods` (`source="standard"`). Each `FuncDoc` also carries
+its `kind` — what the operation does to the world (`read`, `motion`,
+`acquire`, `lifecycle`, `control`, `configure`), declared with
+`@expose_to_api(kind=..., position_key=..., step=...)` or a `"kind"` block in
+`schema_func.json` and used by the field test to drive the operation
+(see *test_helper*, "Kinds"). Per-parameter and return
 descriptions are parsed from Google-style docstring `Args:`/`Returns:`
 sections — write those in your device methods and the generated documentation
 inherits them.

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/docs/device/test_helper.md

@@ -455,7 +455,7 @@ if __name__ == "__main__":
 | 2 | `test_connect_lifecycle` | connect / identity / `check_errors` / disconnect / reconnect, each timed; identity stable across the reconnect |
 | 3 | `test_param_roundtrip` | every writable parameter round-trips; the value read back is written back, so device state is unchanged |
 | 4 | `test_param_constraints` | hardware MIN/MAX and option sets against the schema envelope — a schema wider than the hardware fails |
-| 5 | `test_functions` | every operation on the safe allow-list returns a `dict` |
+| 5 | `test_functions` | every operation on the safe allow-list can be called — by kind: a motion one step out and back, a lifecycle op once, a control op once at rest after the motions |
 | 6 | `test_buffer_drain` | a query abandoned mid-flight must not leave its answer for the next query to consume |
 | 7 | `test_error_recovery` | the device recovers from a forced timeout, and the first command after a reconnect succeeds |
 | 8 | `test_stability` | every queryable parameter and safe op repeated `repetitions` times to collect the statistics |
@@ -464,6 +464,29 @@ if __name__ == "__main__":
 (a `"safe": true` entry in `schema_func.json` is forwarded automatically). Without an allow-list
 the function gate is skipped — no motion or emission operation ever runs unattended.
 
+**Kinds.** *How* an allow-listed operation is called comes from what the module declares it
+does — `@expose_to_api(kind=...)` or a `"kind"` block in `schema_func.json`, read back as
+`OpKind` (`plesty.lib.device.device_utils`):
+
+| kind | the gates |
+|---|---|
+| `read` (default) | called with its declared payload, repeated as it is |
+| `motion` | driven from what `position_key` reports: `target = start ± step` (`relative=True` sends the step itself), then put back; the functions gate fails if it does not come back, the stability gate repeats out-and-back; a motion `slow_op` is a delta from the start and is moved back after the provocation |
+| `acquire` | as `read`, but recorded as acting |
+| `lifecycle` (home, reset) | once, when allow-listed; never repeated |
+| `control` (stop, abort) | once, at rest, after the motions; skipped when nothing moved |
+| `configure` | never called — the round-trip gate covers settings |
+
+```python
+@expose_to_api(kind="motion", position_key="MO.Position", step=1.0)
+def move_absolute(self, position: float) -> float: ...
+```
+
+`op_kinds={"move_absolute": OpKind("motion", position_key="MO.Position", step=1.0)}` on the
+pipeline overrides the declaration wholesale. A motion without `position_key`, `target` (the
+first required argument by default) or `step` fails the gate rather than guessing how far a part
+may move.
+
 **Key parameters:**
 
 | Parameter | Default | Description |
@@ -471,6 +494,7 @@ the function gate is skipped — no motion or emission operation ever runs unatt
 | `repetitions` | `20` | Per-command repeat count in the stability gate |
 | `report_path` | `None` | Base path; `run()` writes `<base>.jsonl` (appended) and `<base>.md` |
 | `safe_ops` / `unsafe_ops` | `None` | Operation allow-list and opt-out list |
+| `op_kinds` | `None` | Per-operation `OpKind` overriding the module's declaration |
 | `op_payloads` | `None` | Explicit payload per operation instead of a generated one |
 | `ignore_keys` | `None` | Config keys excluded from every parameter gate |
 | `drain_probe` | auto | The two distinguishable keys used by the drain and recovery gates |

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/gl-secret-detection-report.json

@@ -19,19 +19,19 @@
       "version": "8.30.1"
     },
     "type": "secret_detection",
-    "start_time": "2026-08-17T15:29:32",
-    "end_time": "2026-08-17T15:29:32",
+    "start_time": "2026-08-18T13:39:46",
+    "end_time": "2026-08-18T13:39:47",
     "status": "success",
     "observability": {
       "events": [
         {
           "event": "collect_secrets_analyzer_scan_metrics_from_pipeline",
-          "time_s": 0.45769703,
+          "time_s": 0.527730295,
           "exit_code": 0,
           "git_strategy": "FetchShallow",
-          "repo_size_kb": 708,
+          "repo_size_kb": 709,
           "commit_count": 1,
-          "bytes_scanned": 220,
+          "bytes_scanned": 317,
           "pipeline_type": "Tag"
         },
         {

plesty_lib-0.3.5.dev3/plesty/lib/device/device_utils.py

@@ -0,0 +1,231 @@
+# SPDX-FileCopyrightText: 2026 Plesty Development Team
+# SPDX-FileContributor: Yunshuang Yuan
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Utility functions for device connectivity and configuration."""
+
+import socket
+from dataclasses import dataclass, replace
+from typing import Any, Callable
+import functools
+import inspect
+
+
+class ResponseParser:
+    """Parser to be used in the base device class. Once registered along with a config parameter,
+    the parser will be called to parse the raw response from `_query_()` function of the device.
+    The parsed result will be used to update the corresponding configuration parameter in the
+    `query()` function.
+    """
+
+    def __call__(self, response, param, **kwargs) -> Any:
+        """Parse the raw response from the device and return a structured result."""
+        # Call the parse method implemented by subclasses
+        return self.parse(response, param=param, **kwargs)
+
+    def parse(self, response, param, **kwargs) -> Any:
+        """Alias for __call__, allowing explicit parsing calls."""
+        raise NotImplementedError(
+            "The parse method should be implemented by subclasses of ResponseParser."
+        )
+
+
+# define decoretor for device methods that require operatability check
+def operatable(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator that checks device operatability before executing the wrapped function."""
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            if not self.is_operatable:
+                raise RuntimeError("Device is not operatable. Please connect to the device first.")
+            return await func(self, *args, **kwargs)
+
+        return async_wrapper
+    else:
+
+        @functools.wraps(func)
+        def sync_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            if not self.is_operatable:
+                raise RuntimeError("Device is not operatable. Please connect to the device first.")
+            return func(self, *args, **kwargs)
+
+        return sync_wrapper
+
+
+# define decoretor for device methods that require error checking after execution
+def error_check(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator that checks for device errors after executing the wrapped function."""
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            result = await func(self, *args, **kwargs)
+            errors = await self.check_errors()
+            if errors:
+                raise RuntimeError(
+                    f"Device reported errors after executing '{func.__name__}': {errors}"
+                )
+            return result
+
+        return async_wrapper
+    else:
+
+        @functools.wraps(func)
+        def sync_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            result = func(self, *args, **kwargs)
+            errors = self.check_errors()
+            if errors:
+                raise RuntimeError(
+                    f"Device reported errors after executing '{func.__name__}': {errors}"
+                )
+            return result
+
+        return sync_wrapper
+
+
+def get_local_ip() -> str:
+    """Return the local IP address of this machine."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        # doesn't need to be reachable
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+    finally:
+        s.close()
+    return ip
+
+
+#: What an operation does to the world, as far as an unattended test needs to
+#: know. Declared once by the module; read by the field test, which decides per
+#: kind how an operation is called, repeated, made slow and put back — instead
+#: of asking the developer to re-derive it for every operation.
+OP_KINDS: tuple[str, ...] = ("read", "motion", "acquire", "lifecycle", "control", "configure")
+
+#: Attribute the exposure marker and the kind are stored under on the method.
+EXPOSE_MARKER = "__plesty_expose_in_api__"
+OP_KIND_MARKER = "__plesty_op_kind__"
+
+
+@dataclass(frozen=True)
+class OpKind:
+    """The class of an operation and, for motion, what the test needs to drive it.
+
+    Attributes:
+        kind: One of :data:`OP_KINDS`. ``read`` returns a value and changes
+            nothing. ``motion`` moves a part whose position a parameter reports.
+            ``acquire`` emits or exposes (a shutter, an exposure) and produces
+            data. ``lifecycle`` is homing, reset, calibration — done once, never
+            on repeat. ``control`` is stop/abort — meaningful only with a motion
+            in flight. ``configure`` changes a setting that outlives the call.
+        position_key: Motion only — the configuration key that reports where
+            the moving part is, in the same units the operation takes.
+        target: Motion only — the argument that receives the target. Defaults
+            to the operation's first required argument.
+        relative: Motion only — the target is a signed step from the current
+            position rather than an absolute position.
+        step: Motion only — how far the field test may move the part, in
+            ``position_key`` units. ``None`` leaves it to the test configuration.
+    """
+
+    kind: str = "read"
+    position_key: str | None = None
+    target: str | None = None
+    relative: bool = False
+    step: float | None = None
+
+    def __post_init__(self) -> None:
+        """Reject a kind nothing knows how to handle."""
+        if self.kind not in OP_KINDS:
+            raise ValueError(f"unknown operation kind {self.kind!r}; expected one of {OP_KINDS}")
+
+    @property
+    def acts(self) -> bool:
+        """Whether the operation changes the world rather than only reading it."""
+        return self.kind != "read"
+
+    def with_defaults(self, **fields: Any) -> "OpKind":
+        """Return a copy where every ``None`` field is filled from *fields*."""
+        filled = {name: value for name, value in fields.items() if getattr(self, name) is None}
+        return replace(self, **filled) if filled else self
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise for a describe payload or a report."""
+        return {
+            "kind": self.kind,
+            "position_key": self.position_key,
+            "target": self.target,
+            "relative": self.relative,
+            "step": self.step,
+        }
+
+    @classmethod
+    def from_options(cls, options: dict[str, Any] | None) -> "OpKind":
+        """Build from registration options or a schema entry (``kind``, ``position_key``, …).
+
+        Args:
+            options: A mapping that may carry the fields of this class. Unknown
+                keys are ignored; a missing ``kind`` is ``read``.
+        """
+        options = options or {}
+        return cls(
+            kind=str(options.get("kind") or "read"),
+            position_key=options.get("position_key"),
+            target=options.get("target"),
+            relative=bool(options.get("relative", False)),
+            step=options.get("step"),
+        )
+
+
+def op_kind_of(func: Any) -> OpKind:
+    """Return the :class:`OpKind` a method was exposed with (``read`` when undeclared)."""
+    if isinstance(func, (staticmethod, classmethod)):
+        func = func.__func__
+    return getattr(func, OP_KIND_MARKER, None) or OpKind()
+
+
+def expose_to_api(
+    func: Any = None,
+    *,
+    kind: str = "read",
+    position_key: str | None = None,
+    target: str | None = None,
+    relative: bool = False,
+    step: float | None = None,
+) -> Any:
+    """Mark a device method so it is listed by the describe endpoint.
+
+    Bare ``@expose_to_api`` marks a ``read``. With arguments it also declares
+    what the operation does, which the field test needs to call it unattended::
+
+        @expose_to_api(kind="motion", position_key="MO.Position")
+        def move_absolute(self, position: float) -> float: ...
+
+        @expose_to_api(kind="motion", position_key="MO.Position", relative=True)
+        def move_relative(self, step: float) -> float: ...
+
+        @expose_to_api(kind="lifecycle")
+        def home_stage(self) -> bool: ...
+
+    Args:
+        func: The method, when used without parentheses.
+        kind: One of :data:`OP_KINDS`.
+        position_key: Motion — the parameter that reports the moving part's position.
+        target: Motion — the argument taking the target; the first required one by default.
+        relative: Motion — the target is a step from the current position.
+        step: Motion — how far the field test may move, in ``position_key`` units.
+    """
+    op_kind = OpKind(
+        kind=kind, position_key=position_key, target=target, relative=relative, step=step
+    )
+
+    def decorate(method: Any) -> Any:
+        real = method.__func__ if isinstance(method, (staticmethod, classmethod)) else method
+        setattr(real, EXPOSE_MARKER, True)
+        setattr(real, OP_KIND_MARKER, op_kind)
+        return method
+
+    if func is not None:
+        return decorate(func)
+    return decorate

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/plesty/lib/device/funcs.py

@@ -14,7 +14,7 @@ import re
 import reprlib
 import numpy as np
 
-from plesty.lib.device.device_utils import ResponseParser
+from plesty.lib.device.device_utils import OpKind, ResponseParser, op_kind_of
 from plesty.lib.data import (
     PlestyArray,
     PlestyTable2D,
@@ -192,6 +192,9 @@ class FuncDoc:
         description: Human-readable description (from the schema or docstring).
         iparams: Input parameters.
         oparams: Output values.
+        kind: What the operation does to the world (see
+            :class:`~plesty.lib.device.device_utils.OpKind`); ``read`` when
+            the module declared nothing.
     """
 
     name: str
@@ -199,6 +202,7 @@ class FuncDoc:
     description: str
     iparams: list["FuncParam"]
     oparams: list["FuncOutput"]
+    kind: OpKind = field(default_factory=OpKind)
 
 
 #: Size-bounded repr for operation log lines, so array-valued parameters do
@@ -450,6 +454,7 @@ class FunctionSystem:
                     description=str(meta.get("registration_options", {}).get("description", "")),
                     iparams=list(meta["iparams"]),
                     oparams=list(meta["oparams"]),
+                    kind=OpKind.from_options(meta.get("registration_options")),
                 )
             )
 
@@ -523,6 +528,7 @@ class FunctionSystem:
             description=docstring,
             iparams=iparams,
             oparams=oparams,
+            kind=op_kind_of(func),
         )
 
     def register_from_op_schema(
@@ -584,6 +590,13 @@ class FunctionSystem:
                 # Marks an operation the on-hardware field test may call
                 # unattended (see plesty.lib.test.field_test.FieldTestPipeline).
                 options.setdefault("safe", bool(op_cfg["safe"]))
+            # What the operation does (OpKind): the field test drives a
+            # "motion" differently from a "read". Validated here so a typo in
+            # the schema fails at registration, not in a test on hardware.
+            for name in ("kind", "position_key", "target", "relative", "step"):
+                if name in op_cfg:
+                    options.setdefault(name, op_cfg[name])
+            OpKind.from_options(options)
 
             self.register_func(
                 op_name,
@@ -821,7 +834,10 @@ class FunctionSystem:
                     "output": self._signature_output_docs(signature, default_type="Any"),
                     "description": description,
                     "parser": None,
-                    "registration_options": {"source": "expose-to-api"},
+                    "registration_options": {
+                        "source": "expose-to-api",
+                        **op_kind_of(func).to_dict(),
+                    },
                     "runtime_request_shape": {"op": name, "params": "dict[str, Any]"},
                 }
 

{plesty_lib-0.3.5.dev2 → plesty_lib-0.3.5.dev3}/plesty/lib/test/client_field_test.py

@@ -67,6 +67,7 @@ from pathlib import Path
 from collections.abc import Sequence
 from typing import Any
 
+from plesty.lib.device.device_utils import OpKind
 from plesty.lib.test.report_artifact import (
     Coverage,
     Instrument,
@@ -148,6 +149,13 @@ class ClientFieldTest:
         safe_ops: Served functions the run may call. Nothing not named here is
             called: the client tier inherits the host tier's safety judgement
             rather than making a second one that could disagree with it.
+        op_kinds: What each operation does, per name, as the host tier was
+            told (:class:`~plesty.lib.device.device_utils.OpKind` or its
+            fields as a mapping). The client cannot read the module's
+            declaration through ``describe``'s flat method list, so the same
+            kinds are handed over: a ``motion`` is driven one ``step`` out
+            from what its ``position_key`` reports and back, a ``lifecycle``
+            once, a ``control`` once after the motions, a ``configure`` never.
         resources: Lockable resources to contend for. Two clients ask for
             these at once, and the second must be refused.
         expected_types: Parameter key to the type it is declared as. The
@@ -182,6 +190,7 @@ class ClientFieldTest:
         safe_ops: Sequence[str] | None = None,
         resources: Sequence[str] | None = None,
         expected_types: dict[str, type] | None = None,
+        op_kinds: dict[str, OpKind | dict[str, Any]] | None = None,
         fixed_threading: bool = True,
         label: str = "",
         instrument: Instrument | None = None,
@@ -200,6 +209,10 @@ class ClientFieldTest:
         self.address = address or f"tcp://127.0.0.1:{_free_port()}"
         self.params = list(params or [])
         self.safe_ops = list(safe_ops or [])
+        self.op_kinds: dict[str, OpKind] = {
+            name: kind if isinstance(kind, OpKind) else OpKind.from_options(dict(kind))
+            for name, kind in (op_kinds or {}).items()
+        }
         self.resources = list(resources or [])
         self._expected_types = dict(expected_types or {})
         self.fixed_threading = fixed_threading
@@ -451,23 +464,89 @@ class ClientFieldTest:
 
         started = time.perf_counter()
         problems: list[str] = []
-        for name in self.safe_ops:
+        answered: dict[str, str] = {}
+        skipped: dict[str, str] = {}
+        kinds = {name: self.op_kinds.get(name, OpKind()) for name in self.safe_ops}
+        # Motions first, controls after — a stop follows something that moved.
+        ordered = sorted(self.safe_ops, key=lambda name: kinds[name].kind == "control")
+        moved = False
+        for name in ordered:
+            kind = kinds[name]
+            if kind.kind == "configure":
+                skipped[name] = "configure: changes a setting that outlives the call; never called"
+                continue
+            if kind.kind == "control" and not moved:
+                skipped[name] = "control: no motion operation is allow-listed to act on"
+                continue
             try:
-                answer = self._timed_call(f"op:{name}", client.call, name)
-                for _ in range(self._repeat(f"op:{name}") - 1):
-                    self._timed_call(f"op:{name}", client.call, name)
+                if kind.kind == "motion":
+                    answer = self._motion_over_the_wire(client, name, kind)
+                    moved = True
+                else:
+                    answer = self._timed_call(f"op:{name}", client.call, name)
+                    # A lifecycle or control operation is done once, whatever
+                    # the host tier's count: it homes, resets or stops.
+                    if kind.kind in ("read", "acquire"):
+                        for _ in range(self._repeat(f"op:{name}") - 1):
+                            self._timed_call(f"op:{name}", client.call, name)
             except Exception as exc:  # noqa: BLE001 - the reason is the result
                 problems.append(f"{name}: raised {type(exc).__name__}: {exc}")
                 continue
-            if not isinstance(answer, dict):
-                problems.append(f"{name}: answered {type(answer).__name__}, not a dict")
-            else:
-                self._called.add(name)
+            # A call that came back is the whole claim of this tier: the
+            # transport carried the request and its answer. What the answer
+            # is shaped like is the host tier's business — it demands a dict
+            # of a schema operation and nothing of an @expose_to_api method,
+            # and describe() flattens both into one list, so demanding a
+            # dict here failed acquire (None) and get_recent_file (str) on a
+            # module whose experiment consumes exactly those (lib#38).
+            answered[name] = type(answer).__name__
+            self._called.add(name)
 
         elapsed = time.perf_counter() - started
         if problems:
             return GateResult("functions", FAIL, elapsed, error="; ".join(problems))
-        return GateResult("functions", PASS, elapsed, evidence={"called": sorted(self._called)})
+        evidence: dict[str, Any] = {"called": sorted(self._called), "answered": answered}
+        if skipped:
+            evidence["skipped"] = skipped
+        return GateResult("functions", PASS, elapsed, evidence=evidence)
+
+    def _motion_over_the_wire(self, client: Any, name: str, kind: OpKind) -> Any:
+        """Drive a motion one step out and back, as many times as the host tier did.
+
+        The host tier's count for a motion is out-and-back pairs, so half of
+        it is the number of pairs to make here; at least one.
+
+        Args:
+            client: A connected client.
+            name: The motion operation.
+            kind: Its declaration — ``position_key``, ``target`` and ``step``
+                must all be known.
+
+        Returns:
+            The answer to the last call.
+
+        Raises:
+            ValueError: If the declaration is incomplete.
+        """
+        if kind.position_key is None or kind.target is None or kind.step is None:
+            missing = [f for f in ("position_key", "target", "step") if getattr(kind, f) is None]
+            raise ValueError(
+                f"motion operation '{name}' declares no {'/'.join(missing)};"
+                " the client tier will not guess how far a part may move."
+            )
+        start = float(
+            self._timed_call(f"query:{kind.position_key}", client.query, kind.position_key)
+        )
+        if kind.relative:
+            out, back = {kind.target: kind.step}, {kind.target: -kind.step}
+        else:
+            out, back = {kind.target: start + kind.step}, {kind.target: start}
+        pairs = max(1, self._repeat(f"op:{name}") // 2)
+        answer: Any = None
+        for _ in range(pairs):
+            self._timed_call(f"op:{name}", lambda: client.call(name, **out))
+            answer = self._timed_call(f"op:{name}", lambda: client.call(name, **back))
+        return answer
 
     def test_session_survives_a_bad_result(self, client: Any) -> GateResult:
         """A call whose result JSON cannot carry must not end the session.