devagent-physical-engine 0.10.0__py3-none-any.whl

devagent_physical_engine/ros2/ur5e_adapter.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from hashlib import sha256
+from pathlib import Path
+from time import monotonic, sleep
+from typing import Any, Mapping
+
+from ..physical_motion import MotionExecutionMetrics, PhysicalMotionPlan
+from ..robot_platform import QualificationState, SimulationTier
+from ..simulation_platform import (
+    AdapterHealth,
+    SimulationAdapterDescriptor,
+    SimulationPlatformError,
+)
+from ..twin import TwinSpec
+from .commands import RosCommandRunner
+from .doctor import RosDoctor
+from .trajectory import (
+    RosTrajectoryError,
+    execute_joint_trajectory,
+    read_joint_state,
+    single_point_motion,
+)
+from .ur5e import UR5eSimulation, UR5eSimulationLauncher
+
+
+UR5E_JOINTS = (
+    "shoulder_pan_joint",
+    "shoulder_lift_joint",
+    "elbow_joint",
+    "wrist_1_joint",
+    "wrist_2_joint",
+    "wrist_3_joint",
+)
+_RESET_GRAPH_HASH = sha256(b"devagent-ur5e-simulation-reset-v1").hexdigest()
+
+
+class UR5eGazeboAdapter:
+    """ROS 2 Gazebo adapter for executing already-compiled UR5e trajectories.
+
+    The trajectory and limited metric scopes start EXPERIMENTAL until this exact
+    v0.9 runtime passes DGX qualification. Twin materialization and pre-execution
+    verification remain NOT_QUALIFIED, so this adapter cannot enter a
+    commissioning-grade PhysicalCampaignRunner.
+    """
+
+    descriptor = SimulationAdapterDescriptor(
+        adapter_id="ur5e_gazebo_measured_v1",
+        backend="gazebo_moveit_ros2",
+        robot_profile_keys=("ur5e",),
+        tier=SimulationTier.PHYSICS,
+        qualification=QualificationState.EXPERIMENTAL,
+        visual_capable=True,
+        headless_capable=False,
+        replay_capable=True,
+        metric_names=frozenset(
+            {
+                "ros_action_round_trip_duration_s",
+                "planned_duration_s",
+                "planned_joint_travel_rad",
+                "final_joint_tracking_error_rad",
+                "endpoint_joint_delta_rad",
+            }
+        ),
+        notes=(
+            "Executes compiled joint trajectories only; high-level task graphs are not executable.",
+            "Cartesian path length and minimum clearance remain unavailable until a measured scene/MoveIt metric collector is attached.",
+        ),
+        trajectory_runtime_qualification=QualificationState.EXPERIMENTAL,
+        twin_environment_qualification=QualificationState.NOT_QUALIFIED,
+        preexecution_verification_qualification=QualificationState.NOT_QUALIFIED,
+        metric_collection_qualification=QualificationState.EXPERIMENTAL,
+    )
+
+    def __init__(
+        self,
+        runner: RosCommandRunner,
+        *,
+        ros_setup: Path | str = "/opt/ros/jazzy/setup.bash",
+        log_dir: Path | str = "~/.devagent/physical-simulation",
+        startup_timeout_s: float = 120.0,
+        reset_duration_s: float = 3.0,
+        start_tolerance_rad: float = 0.03,
+        final_tolerance_rad: float = 0.05,
+    ) -> None:
+        if startup_timeout_s <= 0 or reset_duration_s <= 0:
+            raise ValueError("ur5e_adapter_timeouts_must_be_positive")
+        if start_tolerance_rad <= 0 or final_tolerance_rad <= 0:
+            raise ValueError("ur5e_adapter_tolerances_must_be_positive")
+        self.runner = runner
+        self.ros_setup = Path(ros_setup)
+        self.log_dir = Path(log_dir).expanduser().resolve()
+        self.startup_timeout_s = float(startup_timeout_s)
+        self.reset_duration_s = float(reset_duration_s)
+        self.start_tolerance_rad = float(start_tolerance_rad)
+        self.final_tolerance_rad = float(final_tolerance_rad)
+        self._simulation: UR5eSimulation | None = None
+        self._twin: TwinSpec | None = None
+        self._session_id: str | None = None
+        self._active_case_id: str | None = None
+        self._active_reset_state: dict[str, Any] | None = None
+        self._last_metrics: MotionExecutionMetrics | None = None
+        self._last_state: dict[str, Any] = {}
+        self._records: dict[str, tuple[dict[str, Any], PhysicalMotionPlan]] = {}
+
+    def doctor(self, *, robot_profile_key: str) -> AdapterHealth:
+        if robot_profile_key != "ur5e":
+            return AdapterHealth(False, "unsupported_robot_profile", (robot_profile_key,))
+        try:
+            report = RosDoctor(self.runner, ros_setup=self.ros_setup).run()
+        except Exception as exc:
+            return AdapterHealth(False, "ros_doctor_error", (type(exc).__name__,))
+        if not report.passed:
+            return AdapterHealth(
+                False,
+                "ros_doctor_failed",
+                tuple(f"{item.name}:{item.detail}" for item in report.failures),
+            )
+        return AdapterHealth(True, "ready", ("ROS 2 Jazzy UR5e simulation stack available",))
+
+    def _ready_probe(self) -> tuple[bool, str]:
+        controllers = self.runner.run(
+            ["ros2", "control", "list_controllers"], timeout_s=5.0
+        )
+        if not controllers.ok:
+            return False, "controller_manager_unavailable"
+        active = any(
+            "joint_trajectory_controller" in line.lower()
+            and line.split()
+            and line.split()[-1].lower() == "active"
+            for line in controllers.stdout.splitlines()
+        )
+        if not active:
+            return False, "joint_trajectory_controller_not_active"
+        topics = self.runner.run(["ros2", "topic", "list"], timeout_s=5.0)
+        if not topics.ok:
+            return False, "topic_list_failed"
+        if "/joint_states" not in {line.strip() for line in topics.stdout.splitlines()}:
+            return False, "joint_states_missing"
+        actions = self.runner.run(["ros2", "action", "list"], timeout_s=5.0)
+        if not actions.ok:
+            return False, "action_list_failed"
+        if "/joint_trajectory_controller/follow_joint_trajectory" not in {
+            line.strip() for line in actions.stdout.splitlines()
+        }:
+            return False, "trajectory_action_missing"
+        return True, "controller/topic/action ready"
+
+    def _wait_ready(self) -> None:
+        started = monotonic()
+        last = "not_ready"
+        while monotonic() - started < self.startup_timeout_s:
+            simulation = self._simulation
+            if simulation is None or not simulation.running:
+                raise SimulationPlatformError("ur5e_simulation_exited_early")
+            try:
+                ready, last = self._ready_probe()
+            except Exception as exc:
+                ready = False
+                last = f"probe_error:{type(exc).__name__}"
+            if ready:
+                return
+            sleep(2.0)
+        raise SimulationPlatformError(f"ur5e_simulation_startup_timeout:{last}")
+
+    def prepare(self, *, twin: TwinSpec) -> str:
+        if self._simulation is not None:
+            raise SimulationPlatformError("ur5e_adapter_already_prepared")
+        if twin.robot_profile_key != "ur5e":
+            raise SimulationPlatformError("ur5e_adapter_twin_robot_mismatch")
+        health = self.doctor(robot_profile_key="ur5e")
+        if not health.ready:
+            raise SimulationPlatformError(f"ur5e_adapter_not_ready:{health.code}")
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        log_path = self.log_dir / f"ur5e-measured-{timestamp}.log"
+        self._simulation = UR5eSimulationLauncher(self.runner).launch(log_path=log_path)
+        self._twin = twin
+        self._session_id = f"ur5e-gazebo-{timestamp}"
+        try:
+            self._wait_ready()
+            snapshot = read_joint_state(self.runner)
+            snapshot.ordered(UR5E_JOINTS)
+        except Exception:
+            self.stop()
+            raise
+        return self._session_id
+
+    def _require_prepared(self) -> TwinSpec:
+        if self._simulation is None or not self._simulation.running or self._twin is None:
+            raise SimulationPlatformError("ur5e_adapter_not_prepared")
+        return self._twin
+
+    def reset(self, *, case_id: str, state: Mapping[str, Any]) -> None:
+        twin = self._require_prepared()
+        if not case_id.strip():
+            raise SimulationPlatformError("physical_case_id_required")
+        allowed = {"initial_joint_positions_rad"}
+        unknown = set(state) - allowed
+        if unknown:
+            raise SimulationPlatformError(
+                "unsupported_physical_reset_state:" + ",".join(sorted(unknown))
+            )
+        target_raw = state.get("initial_joint_positions_rad")
+        if not isinstance(target_raw, (list, tuple)) or len(target_raw) != len(UR5E_JOINTS):
+            raise SimulationPlatformError("physical_case_initial_joint_positions_required")
+        target = tuple(float(value) for value in target_raw)
+        snapshot = read_joint_state(self.runner)
+        current = snapshot.ordered(UR5E_JOINTS)
+        reset_motion = single_point_motion(
+            motion_id=f"RESET-{case_id}",
+            robot_profile_key="ur5e",
+            joint_names=UR5E_JOINTS,
+            current_positions_rad=current,
+            target_positions_rad=target,
+            duration_s=self.reset_duration_s,
+            source_graph_hash=_RESET_GRAPH_HASH,
+            twin_hash=twin.fingerprint,
+        )
+        execute_joint_trajectory(self.runner, reset_motion)
+        after = read_joint_state(self.runner).ordered(UR5E_JOINTS)
+        error = max(abs(a - b) for a, b in zip(target, after))
+        if error > self.start_tolerance_rad:
+            raise SimulationPlatformError(f"physical_reset_tracking_error:{error:.6f}")
+        self._active_case_id = case_id
+        self._active_reset_state = {"initial_joint_positions_rad": list(target)}
+        self._last_metrics = None
+        self._last_state = {
+            "case_id": case_id,
+            "reset_positions_rad": list(after),
+            "reset_error_rad": error,
+        }
+
+    def execute_motion(self, *, motion: PhysicalMotionPlan) -> MotionExecutionMetrics:
+        twin = self._require_prepared()
+        if self._active_case_id is None or self._active_reset_state is None:
+            raise SimulationPlatformError("physical_case_not_reset")
+        if motion.robot_profile_key != "ur5e":
+            raise SimulationPlatformError("motion_robot_profile_mismatch")
+        if motion.twin_hash != twin.fingerprint:
+            raise SimulationPlatformError("motion_twin_hash_mismatch")
+        if set(motion.joint_names) != set(UR5E_JOINTS) or len(motion.joint_names) != 6:
+            raise SimulationPlatformError("ur5e_motion_joint_set_invalid")
+
+        before = read_joint_state(self.runner).ordered(motion.joint_names)
+        start_error = max(
+            abs(actual - expected)
+            for actual, expected in zip(before, motion.points[0].positions_rad)
+        )
+        if start_error > self.start_tolerance_rad:
+            raise SimulationPlatformError(f"motion_start_state_mismatch:{start_error:.6f}")
+
+        try:
+            command = execute_joint_trajectory(self.runner, motion)
+            after = read_joint_state(self.runner).ordered(motion.joint_names)
+            final_error = max(
+                abs(actual - expected)
+                for actual, expected in zip(after, motion.points[-1].positions_rad)
+            )
+            endpoint_delta = sum(abs(a - b) for a, b in zip(before, after))
+            success = final_error <= self.final_tolerance_rad
+            failures = () if success else ("final_tracking_error_exceeded",)
+            metrics = MotionExecutionMetrics(
+                success=success,
+                observed_duration_s=command.duration_s,
+                planned_duration_s=motion.planned_duration_s,
+                planned_joint_travel_rad=motion.joint_travel_rad,
+                measured_joint_travel_rad=None,
+                max_tracking_error_rad=final_error,
+                path_length_m=None,
+                min_clearance_m=None,
+                final_tcp_error_m=None,
+                energy_proxy=None,
+                failure_codes=failures,
+                metrics_origin="ros2_action_round_trip_simulation",
+            )
+        except RosTrajectoryError as exc:
+            metrics = MotionExecutionMetrics(
+                success=False,
+                observed_duration_s=None,
+                planned_duration_s=motion.planned_duration_s,
+                planned_joint_travel_rad=motion.joint_travel_rad,
+                failure_codes=(str(exc).split(":", 1)[0],),
+                metrics_origin="ros2_action_round_trip_simulation",
+            )
+            endpoint_delta = None
+            after = before
+
+        self._last_metrics = metrics
+        self._last_state = {
+            "case_id": self._active_case_id,
+            "motion_id": motion.motion_id,
+            "motion_hash": motion.fingerprint,
+            "final_joint_positions_rad": list(after),
+            "endpoint_joint_delta_rad": endpoint_delta,
+            "metrics": metrics.to_dict(),
+        }
+        self._records[self._active_case_id] = (dict(self._active_reset_state), motion)
+        return metrics
+
+    def collect_metrics(self) -> Mapping[str, float | int | bool | str | None]:
+        if self._last_metrics is None:
+            raise SimulationPlatformError("physical_metrics_not_available")
+        metrics = self._last_metrics
+        return {
+            "success": metrics.success,
+            "ros_action_round_trip_duration_s": metrics.observed_duration_s,
+            "planned_duration_s": metrics.planned_duration_s,
+            "planned_joint_travel_rad": metrics.planned_joint_travel_rad,
+            "final_joint_tracking_error_rad": metrics.max_tracking_error_rad,
+            "endpoint_joint_delta_rad": self._last_state.get("endpoint_joint_delta_rad"),
+            "path_length_m": metrics.path_length_m,
+            "min_clearance_m": metrics.min_clearance_m,
+            "metrics_origin": metrics.metrics_origin,
+        }
+
+    def capture_state(self) -> Mapping[str, Any]:
+        self._require_prepared()
+        return dict(self._last_state)
+
+    def replay(self, *, case_id: str) -> Mapping[str, Any]:
+        record = self._records.get(case_id)
+        if record is None:
+            raise SimulationPlatformError(f"physical_replay_case_not_found:{case_id}")
+        reset_state, motion = record
+        original_hash = motion.fingerprint
+        self.reset(case_id=case_id, state=reset_state)
+        metrics = self.execute_motion(motion=motion)
+        return {
+            "case_id": case_id,
+            "motion_hash": original_hash,
+            "replayed_motion_hash": motion.fingerprint,
+            "same_motion": original_hash == motion.fingerprint,
+            "metrics": metrics.to_dict(),
+            "state": dict(self._last_state),
+        }
+
+    def stop(self) -> None:
+        simulation = self._simulation
+        self._simulation = None
+        self._twin = None
+        self._session_id = None
+        self._active_case_id = None
+        self._active_reset_state = None
+        self._last_metrics = None
+        self._last_state = {}
+        if simulation is not None:
+            simulation.stop()

devagent_physical_engine/ros2/ur5e_v10_adapter.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime, timezone
+from pathlib import Path
+from time import sleep
+from typing import Any, Mapping
+
+from ..physical_motion import MotionExecutionMetrics, PhysicalMotionPlan
+from ..robot_platform import QualificationState, SimulationTier
+from ..simulation_platform import SimulationAdapterDescriptor, SimulationPlatformError
+from ..twin import TwinSpec
+from ..twin_materialization import CanonicalTwinMaterialization, TwinMaterializer
+from .frame_alignment import FrameAlignmentReceipt, FrameAlignmentVerifier
+from .gazebo_world import GazeboWorldReceipt, GazeboWorldVerifier
+from .measured_motion import FkMetricReceipt, JointMotionAnalysis, MoveItFkMetricBridge, analyze_joint_state_record, load_joint_state_record
+from .moveit_scene import MoveItSceneBridge, MoveItSceneReceipt
+from .preexecution import MoveItPreExecutionVerifier
+from .trajectory import read_joint_state
+from .ur5e import UR5eSimulationLauncher
+from .ur5e_adapter import UR5E_JOINTS, UR5eGazeboAdapter
+
+
+class UR5eCanonicalTwinAdapter(UR5eGazeboAdapter):
+    """v0.10 UR5e adapter binding one Twin to Gazebo, TF, and MoveIt.
+
+    The adapter remains EXPERIMENTAL until executable qualification promotes
+    each scope. Pre-execution checking is discrete rather than continuous and
+    minimum-clearance measurement remains unavailable.
+    """
+
+    descriptor = SimulationAdapterDescriptor(
+        adapter_id="ur5e_gazebo_canonical_v2",
+        backend="gazebo_moveit_ros2",
+        robot_profile_keys=("ur5e",),
+        tier=SimulationTier.PHYSICS,
+        qualification=QualificationState.EXPERIMENTAL,
+        visual_capable=True,
+        headless_capable=False,
+        replay_capable=True,
+        metric_names=frozenset({
+            "measured_motion_duration_s",
+            "planned_duration_s",
+            "planned_joint_travel_rad",
+            "measured_joint_travel_rad",
+            "final_joint_tracking_error_rad",
+            "measured_tcp_path_length_m",
+            "final_tcp_error_m",
+            "materialization_hash",
+            "moveit_scene_hash",
+        }),
+        notes=(
+            "One canonical Twin materialization drives Gazebo and MoveIt.",
+            "Gazebo models, TF alignment, and MoveIt PlanningScene are read back and verified.",
+            "Pre-execution state validity is sampled/discrete, not continuous collision checking.",
+            "Minimum-clearance measurement is not yet qualified and remains unavailable.",
+            "Real robot execution remains locked.",
+        ),
+        trajectory_runtime_qualification=QualificationState.EXPERIMENTAL,
+        twin_environment_qualification=QualificationState.EXPERIMENTAL,
+        preexecution_verification_qualification=QualificationState.EXPERIMENTAL,
+        metric_collection_qualification=QualificationState.EXPERIMENTAL,
+    )
+
+    def __init__(
+        self,
+        runner,
+        *,
+        ros_setup: Path | str = "/opt/ros/jazzy/setup.bash",
+        log_dir: Path | str = "~/.devagent/physical-simulation-v10",
+        startup_timeout_s: float = 120.0,
+        reset_duration_s: float = 3.0,
+        start_tolerance_rad: float = 0.03,
+        final_tolerance_rad: float = 0.05,
+        planning_frame: str = "base_link",
+        planning_group: str = "ur_manipulator",
+        fk_link_name: str = "tool0",
+    ) -> None:
+        super().__init__(
+            runner,
+            ros_setup=ros_setup,
+            log_dir=log_dir,
+            startup_timeout_s=startup_timeout_s,
+            reset_duration_s=reset_duration_s,
+            start_tolerance_rad=start_tolerance_rad,
+            final_tolerance_rad=final_tolerance_rad,
+        )
+        self.materializer = TwinMaterializer(planning_frame=planning_frame)
+        self.frame_verifier = FrameAlignmentVerifier(runner)
+        self.gazebo_verifier = GazeboWorldVerifier(runner)
+        self.scene_bridge = MoveItSceneBridge(runner, work_dir=self.log_dir / "moveit-scenes")
+        self.preexecution_verifier = MoveItPreExecutionVerifier(
+            runner,
+            work_dir=self.log_dir / "preexecution",
+            planning_group=planning_group,
+        )
+        self.fk_bridge = MoveItFkMetricBridge(
+            runner,
+            work_dir=self.log_dir / "fk-metrics",
+            planning_frame=planning_frame,
+            link_name=fk_link_name,
+        )
+        self._materialization: CanonicalTwinMaterialization | None = None
+        self._frame_receipt: FrameAlignmentReceipt | None = None
+        self._gazebo_receipt: GazeboWorldReceipt | None = None
+        self._scene_receipt: MoveItSceneReceipt | None = None
+        self._last_preexecution = None
+        self._last_joint_analysis: JointMotionAnalysis | None = None
+        self._last_fk_receipt: FkMetricReceipt | None = None
+
+    def prepare(self, *, twin: TwinSpec) -> str:
+        if self._simulation is not None:
+            raise SimulationPlatformError("ur5e_adapter_already_prepared")
+        if twin.robot_profile_key != "ur5e":
+            raise SimulationPlatformError("ur5e_adapter_twin_robot_mismatch")
+
+        materialization_result = self.materializer.compile(twin)
+        if not materialization_result.ready:
+            codes = ",".join(issue.code for issue in materialization_result.issues)
+            raise SimulationPlatformError(f"twin_materialization_blocked:{codes}")
+        materialization = materialization_result.materialization
+        assert materialization is not None
+
+        health = self.doctor(robot_profile_key="ur5e")
+        if not health.ready:
+            raise SimulationPlatformError(f"ur5e_adapter_not_ready:{health.code}")
+
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        world_path = materialization.write_sdf(self.log_dir / "worlds" / f"{materialization.fingerprint}.sdf")
+        log_path = self.log_dir / f"ur5e-canonical-{timestamp}.log"
+        self._simulation = UR5eSimulationLauncher(self.runner).launch(log_path=log_path, world_file=world_path)
+        self._twin = twin
+        self._materialization = materialization
+        self._session_id = f"ur5e-gazebo-canonical-{timestamp}"
+        try:
+            self._wait_ready()
+            snapshot = read_joint_state(self.runner)
+            snapshot.ordered(UR5E_JOINTS)
+            self._frame_receipt = self.frame_verifier.verify_identity(
+                parent_frame="world",
+                child_frame=materialization.planning_frame,
+            )
+            self._gazebo_receipt = self.gazebo_verifier.verify(materialization)
+            self._scene_receipt = self.scene_bridge.apply_and_verify(materialization)
+        except Exception:
+            self.stop()
+            raise
+        return self._session_id
+
+    def _require_materialization(self) -> CanonicalTwinMaterialization:
+        self._require_prepared()
+        if self._materialization is None:
+            raise SimulationPlatformError("canonical_materialization_missing")
+        if self._frame_receipt is None or self._gazebo_receipt is None or self._scene_receipt is None:
+            raise SimulationPlatformError("canonical_materialization_unverified")
+        return self._materialization
+
+    def _start_joint_recorder(self, *, motion_hash: str) -> tuple[object, Path]:
+        helper = Path(__file__).with_name("joint_state_recorder.py").resolve()
+        output = self.log_dir / "measurements" / f"{motion_hash}.joint-states.json"
+        output.parent.mkdir(parents=True, exist_ok=True)
+        log_path = output.with_suffix(".recorder.log")
+        process = self.runner.start(
+            (
+                "python3",
+                str(helper),
+                "--output",
+                str(output),
+                "--topic",
+                "/joint_states",
+                "--max-samples",
+                "20000",
+            ),
+            log_path=log_path,
+        )
+        sleep(0.25)
+        return process, output
+
+    def execute_motion(self, *, motion: PhysicalMotionPlan) -> MotionExecutionMetrics:
+        materialization = self._require_materialization()
+        if motion.twin_hash != materialization.twin_hash:
+            raise SimulationPlatformError("motion_twin_hash_mismatch")
+
+        twin = self._require_prepared()
+        customer_plan = motion.metadata.get("customer_plan") is not False
+        if customer_plan:
+            if twin.tool is not None and motion.metadata.get("tool_collision_model_verified") is not True:
+                raise SimulationPlatformError("tool_collision_model_unverified")
+            if twin.workpiece_entity_id is not None and motion.metadata.get("workpiece_manipulation") is not False:
+                raise SimulationPlatformError("workpiece_attachment_state_unqualified")
+
+        preexecution = self.preexecution_verifier.verify(motion=motion, materialization=materialization)
+        self._last_preexecution = preexecution
+        if not preexecution.verified:
+            raise SimulationPlatformError(
+                "motion_preexecution_verification_failed:" + ",".join(preexecution.failure_codes)
+            )
+
+        recorder = None
+        record_path: Path | None = None
+        try:
+            recorder, record_path = self._start_joint_recorder(motion_hash=motion.fingerprint)
+            metrics = super().execute_motion(motion=motion)
+        finally:
+            if recorder is not None:
+                self.runner.stop(recorder, timeout_s=3.0)
+
+        if not metrics.success:
+            return metrics
+        if record_path is None:
+            raise SimulationPlatformError("joint_state_measurement_missing")
+
+        payload = load_joint_state_record(record_path)
+        analysis = analyze_joint_state_record(
+            payload,
+            joint_names=motion.joint_names,
+            start_positions_rad=motion.points[0].positions_rad,
+            final_positions_rad=motion.points[-1].positions_rad,
+            final_tolerance_rad=self.final_tolerance_rad,
+        )
+        fk_receipt = self.fk_bridge.compute(
+            motion_hash=motion.fingerprint,
+            joint_names=motion.joint_names,
+            samples=analysis.samples,
+            target_positions_rad=motion.points[-1].positions_rad,
+        )
+
+        enhanced = replace(
+            metrics,
+            observed_duration_s=analysis.duration_s,
+            measured_joint_travel_rad=analysis.measured_joint_travel_rad,
+            max_tracking_error_rad=analysis.final_tracking_error_rad,
+            path_length_m=fk_receipt.path_length_m,
+            final_tcp_error_m=fk_receipt.final_tcp_error_m,
+            metrics_origin="ros_joint_state_plus_moveit_fk_simulation",
+        )
+        self._last_metrics = enhanced
+        self._last_joint_analysis = analysis
+        self._last_fk_receipt = fk_receipt
+        self._last_state = {
+            **self._last_state,
+            "metrics": enhanced.to_dict(),
+            "joint_motion_analysis": analysis.to_dict(),
+            "fk_metrics": fk_receipt.to_dict(),
+            "preexecution": preexecution.to_dict(),
+        }
+        return enhanced
+
+    def collect_metrics(self) -> Mapping[str, float | int | bool | str | None]:
+        metrics = dict(super().collect_metrics())
+        materialization = self._materialization
+        scene = self._scene_receipt
+        if self._last_metrics is not None:
+            metrics.update({
+                "measured_motion_duration_s": self._last_metrics.observed_duration_s,
+                "measured_joint_travel_rad": self._last_metrics.measured_joint_travel_rad,
+                "measured_tcp_path_length_m": self._last_metrics.path_length_m,
+                "final_tcp_error_m": self._last_metrics.final_tcp_error_m,
+            })
+        metrics["materialization_hash"] = materialization.fingerprint if materialization is not None else None
+        metrics["moveit_scene_hash"] = scene.observed_scene_hash if scene is not None else None
+        return metrics
+
+    def capture_state(self) -> Mapping[str, Any]:
+        state = dict(super().capture_state())
+        state.update({
+            "materialization": (
+                {
+                    "twin_hash": self._materialization.twin_hash,
+                    "materialization_hash": self._materialization.fingerprint,
+                    "scene_hash": self._materialization.scene_hash,
+                }
+                if self._materialization is not None
+                else None
+            ),
+            "frame_alignment": self._frame_receipt.to_dict() if self._frame_receipt is not None else None,
+            "gazebo_world": self._gazebo_receipt.to_dict() if self._gazebo_receipt is not None else None,
+            "moveit_scene": self._scene_receipt.to_dict() if self._scene_receipt is not None else None,
+            "preexecution": self._last_preexecution.to_dict() if self._last_preexecution is not None else None,
+        })
+        return state
+
+    def stop(self) -> None:
+        self._materialization = None
+        self._frame_receipt = None
+        self._gazebo_receipt = None
+        self._scene_receipt = None
+        self._last_preexecution = None
+        self._last_joint_analysis = None
+        self._last_fk_receipt = None
+        super().stop()