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

devagent_physical_engine/ros2/frame_alignment.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+from math import acos
+from pathlib import Path
+from typing import Any
+
+from ..simulation_platform import SimulationPlatformError
+from .commands import RosCommandRunner
+
+
+@dataclass(frozen=True, slots=True)
+class FrameAlignmentReceipt:
+    verified: bool
+    code: str
+    parent_frame: str
+    child_frame: str
+    translation_error_m: float
+    rotation_error_rad: float
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class FrameAlignmentVerifier:
+    """Verify the simulator world and MoveIt planning frame share the expected origin."""
+
+    def __init__(self, runner: RosCommandRunner, *, timeout_s: float = 10.0, translation_tolerance_m: float = 1e-5, rotation_tolerance_rad: float = 1e-5) -> None:
+        if timeout_s <= 0 or translation_tolerance_m <= 0 or rotation_tolerance_rad <= 0:
+            raise ValueError("frame_alignment_limits_invalid")
+        self.runner = runner
+        self.timeout_s = float(timeout_s)
+        self.translation_tolerance_m = float(translation_tolerance_m)
+        self.rotation_tolerance_rad = float(rotation_tolerance_rad)
+
+    def verify_identity(self, *, parent_frame: str = "world", child_frame: str = "base_link") -> FrameAlignmentReceipt:
+        helper = Path(__file__).with_name("tf_probe.py").resolve()
+        result = self.runner.run(
+            ("python3", str(helper), "--parent", parent_frame, "--child", child_frame, "--timeout", format(self.timeout_s, ".6g")),
+            timeout_s=self.timeout_s + 5.0,
+        )
+        try:
+            payload = json.loads(result.stdout.strip().splitlines()[-1])
+        except (IndexError, json.JSONDecodeError) as exc:
+            raise SimulationPlatformError("tf_probe_output_invalid") from exc
+        if not result.ok or not isinstance(payload, dict) or not payload.get("success"):
+            code = payload.get("code") if isinstance(payload, dict) else "tf_probe_failed"
+            raise SimulationPlatformError(f"frame_alignment_probe_failed:{code}")
+        translation = tuple(float(v) for v in payload.get("translation_m") or ())
+        quaternion = tuple(float(v) for v in payload.get("quaternion_xyzw") or ())
+        if len(translation) != 3 or len(quaternion) != 4:
+            raise SimulationPlatformError("tf_probe_shape_invalid")
+        translation_error = max(abs(value) for value in translation)
+        # q and -q represent the same rotation; identity angular distance is 2*acos(|w|).
+        rotation_error = 2.0 * acos(max(0.0, min(1.0, abs(quaternion[3]))))
+        if translation_error > self.translation_tolerance_m:
+            raise SimulationPlatformError(f"frame_translation_mismatch:{translation_error:.9f}")
+        if rotation_error > self.rotation_tolerance_rad:
+            raise SimulationPlatformError(f"frame_rotation_mismatch:{rotation_error:.9f}")
+        return FrameAlignmentReceipt(True, "frame_alignment_verified", parent_frame, child_frame, translation_error, rotation_error)

devagent_physical_engine/ros2/gazebo_world.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from math import asin, atan2, pi
+import re
+from typing import Any
+
+from ..simulation_platform import SimulationPlatformError
+from ..twin_materialization import CanonicalTwinMaterialization
+from .commands import RosCommandRunner
+
+
+@dataclass(frozen=True, slots=True)
+class GazeboWorldReceipt:
+    verified: bool
+    code: str
+    twin_hash: str
+    materialization_hash: str
+    expected_model_count: int
+    observed_model_count: int
+    max_position_error_m: float | None = None
+    max_orientation_error_rad: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _rpy(quaternion: tuple[float, float, float, float]) -> tuple[float, float, float]:
+    x, y, z, w = quaternion
+    return (
+        atan2(2 * (w * x + y * z), 1 - 2 * (x * x + y * y)),
+        asin(max(-1.0, min(1.0, 2 * (w * y - z * x)))),
+        atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z)),
+    )
+
+
+def _angle_error(first: float, second: float) -> float:
+    return abs((first - second + pi) % (2 * pi) - pi)
+
+
+def _parse_model_names(text: str) -> set[str]:
+    names: set[str] = set()
+    for line in text.splitlines():
+        match = re.match(r"\s*-\s+(.+?)\s*$", line)
+        if match:
+            names.add(match.group(1))
+    return names
+
+
+def _parse_pose(text: str):
+    triples: list[tuple[float, float, float]] = []
+    pattern = re.compile(r"\[\s*([-+0-9.eE]+)\s*\|\s*([-+0-9.eE]+)\s*\|\s*([-+0-9.eE]+)\s*\]")
+    for match in pattern.finditer(text):
+        triples.append(tuple(float(match.group(index)) for index in range(1, 4)))
+    if len(triples) < 2:
+        raise SimulationPlatformError("gazebo_model_pose_output_invalid")
+    return triples[0], triples[1]
+
+
+class GazeboWorldVerifier:
+    """Read back canonical model identities and poses from running Gazebo."""
+
+    def __init__(
+        self,
+        runner: RosCommandRunner,
+        *,
+        timeout_s: float = 10.0,
+        position_tolerance_m: float = 1e-4,
+        orientation_tolerance_rad: float = 1e-4,
+        dynamic_position_tolerance_m: float = 0.01,
+        dynamic_orientation_tolerance_rad: float = 0.01,
+    ) -> None:
+        if (
+            timeout_s <= 0
+            or position_tolerance_m <= 0
+            or orientation_tolerance_rad <= 0
+            or dynamic_position_tolerance_m <= 0
+            or dynamic_orientation_tolerance_rad <= 0
+        ):
+            raise ValueError("gazebo_world_verifier_limits_invalid")
+        self.runner = runner
+        self.timeout_s = float(timeout_s)
+        self.position_tolerance_m = float(position_tolerance_m)
+        self.orientation_tolerance_rad = float(orientation_tolerance_rad)
+        self.dynamic_position_tolerance_m = float(dynamic_position_tolerance_m)
+        self.dynamic_orientation_tolerance_rad = float(dynamic_orientation_tolerance_rad)
+
+    def verify(self, materialization: CanonicalTwinMaterialization) -> GazeboWorldReceipt:
+        listed = self.runner.run(("gz", "model", "--list"), timeout_s=self.timeout_s)
+        if not listed.ok:
+            raise SimulationPlatformError("gazebo_model_list_failed")
+        observed = _parse_model_names(listed.stdout + "\n" + listed.stderr)
+        expected = {item.backend_id for item in materialization.objects}
+        missing = sorted(expected - observed)
+        if missing:
+            raise SimulationPlatformError("gazebo_materialized_models_missing:" + ",".join(missing))
+
+        max_position = 0.0
+        max_orientation = 0.0
+        for item in materialization.objects:
+            result = self.runner.run(("gz", "model", "-m", item.backend_id, "--pose"), timeout_s=self.timeout_s)
+            if not result.ok:
+                raise SimulationPlatformError(f"gazebo_model_pose_failed:{item.backend_id}")
+            position, orientation = _parse_pose(result.stdout + "\n" + result.stderr)
+            position_error = max(abs(first - second) for first, second in zip(position, item.position_m))
+            orientation_error = max(_angle_error(first, second) for first, second in zip(orientation, _rpy(item.quaternion_xyzw)))
+            max_position = max(max_position, position_error)
+            max_orientation = max(max_orientation, orientation_error)
+            position_tolerance = self.position_tolerance_m if item.static else self.dynamic_position_tolerance_m
+            orientation_tolerance = self.orientation_tolerance_rad if item.static else self.dynamic_orientation_tolerance_rad
+            if position_error > position_tolerance:
+                raise SimulationPlatformError(f"gazebo_model_position_mismatch:{item.backend_id}:{position_error:.9f}")
+            if orientation_error > orientation_tolerance:
+                raise SimulationPlatformError(f"gazebo_model_orientation_mismatch:{item.backend_id}:{orientation_error:.9f}")
+
+        return GazeboWorldReceipt(
+            True,
+            "gazebo_world_readback_verified",
+            materialization.twin_hash,
+            materialization.fingerprint,
+            len(expected),
+            len(expected & observed),
+            max_position,
+            max_orientation,
+        )

devagent_physical_engine/ros2/joint_state_recorder.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--topic", default="/joint_states")
+    parser.add_argument("--max-samples", type=int, default=20000)
+    args = parser.parse_args()
+    output = Path(args.output).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    samples: list[dict[str, object]] = []
+    overflow = False
+
+    import rclpy
+    from sensor_msgs.msg import JointState
+
+    rclpy.init()
+    node = rclpy.create_node("devagent_joint_state_recorder")
+    started_ns: int | None = None
+
+    def callback(message: JointState) -> None:
+        nonlocal started_ns, overflow
+        stamp = message.header.stamp
+        stamped_ns = int(stamp.sec) * 1_000_000_000 + int(stamp.nanosec)
+        now_ns = stamped_ns if stamped_ns > 0 else node.get_clock().now().nanoseconds
+        if started_ns is None:
+            started_ns = now_ns
+        if len(samples) >= int(args.max_samples):
+            overflow = True
+            return
+        samples.append({
+            "time_s": (now_ns - started_ns) / 1_000_000_000.0,
+            "names": list(message.name),
+            "positions_rad": list(message.position),
+        })
+
+    subscription = node.create_subscription(JointState, args.topic, callback, 50)
+    try:
+        rclpy.spin(node)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        payload = {
+            "topic": args.topic,
+            "sample_count": len(samples),
+            "overflow": overflow,
+            "samples": samples,
+        }
+        temporary = output.with_suffix(output.suffix + ".tmp")
+        temporary.write_text(json.dumps(payload, separators=(",", ":"), allow_nan=False), encoding="utf-8")
+        temporary.replace(output)
+        node.destroy_subscription(subscription)
+        node.destroy_node()
+        rclpy.shutdown()
+    return 0 if samples and not overflow else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devagent_physical_engine/ros2/measured_motion.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+from math import isfinite
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from ..simulation_platform import SimulationPlatformError
+from .commands import RosCommandRunner
+
+
+@dataclass(frozen=True, slots=True)
+class RecordedJointSample:
+    time_s: float
+    positions_rad: tuple[float, ...]
+
+    def __post_init__(self) -> None:
+        if not isfinite(self.time_s) or self.time_s < 0:
+            raise ValueError("recorded_joint_time_invalid")
+        if not self.positions_rad or any(not isfinite(value) for value in self.positions_rad):
+            raise ValueError("recorded_joint_positions_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class JointMotionAnalysis:
+    duration_s: float
+    measured_joint_travel_rad: float
+    final_tracking_error_rad: float
+    samples: tuple[RecordedJointSample, ...]
+
+    def __post_init__(self) -> None:
+        for value in (self.duration_s, self.measured_joint_travel_rad, self.final_tracking_error_rad):
+            if not isfinite(value) or value < 0:
+                raise ValueError("joint_motion_analysis_invalid")
+        if len(self.samples) < 2:
+            raise ValueError("joint_motion_analysis_samples_required")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "duration_s": self.duration_s,
+            "measured_joint_travel_rad": self.measured_joint_travel_rad,
+            "final_tracking_error_rad": self.final_tracking_error_rad,
+            "sample_count": len(self.samples),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class FkMetricReceipt:
+    verified: bool
+    code: str
+    path_length_m: float
+    final_tcp_error_m: float
+    sample_count: int
+    link_name: str
+    planning_frame: str
+
+    def __post_init__(self) -> None:
+        if not self.code.strip() or not self.link_name.strip() or not self.planning_frame.strip():
+            raise ValueError("fk_metric_receipt_identity_invalid")
+        if not self.verified:
+            raise ValueError("fk_metric_receipt_requires_verified")
+        if (
+            not isfinite(self.path_length_m)
+            or self.path_length_m < 0
+            or not isfinite(self.final_tcp_error_m)
+            or self.final_tcp_error_m < 0
+            or self.sample_count < 1
+        ):
+            raise ValueError("fk_metric_receipt_value_invalid")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _ordered_positions(sample: Mapping[str, Any], joint_names: tuple[str, ...]) -> tuple[float, ...]:
+    names_raw = sample.get("names")
+    positions_raw = sample.get("positions_rad")
+    if not isinstance(names_raw, list) or not isinstance(positions_raw, list):
+        raise ValueError("joint_record_sample_shape_invalid")
+    values = {str(name): float(position) for name, position in zip(names_raw, positions_raw)}
+    missing = [name for name in joint_names if name not in values]
+    if missing:
+        raise ValueError("joint_record_missing:" + ",".join(sorted(missing)))
+    ordered = tuple(values[name] for name in joint_names)
+    if any(not isfinite(value) for value in ordered):
+        raise ValueError("joint_record_non_finite")
+    return ordered
+
+
+def analyze_joint_state_record(
+    payload: Mapping[str, Any],
+    *,
+    joint_names: tuple[str, ...],
+    start_positions_rad: tuple[float, ...],
+    final_positions_rad: tuple[float, ...],
+    departure_threshold_rad: float = 1e-4,
+    final_tolerance_rad: float = 0.05,
+) -> JointMotionAnalysis:
+    if (
+        departure_threshold_rad <= 0
+        or final_tolerance_rad <= 0
+        or len(start_positions_rad) != len(joint_names)
+        or len(final_positions_rad) != len(joint_names)
+    ):
+        raise ValueError("joint_motion_analysis_limits_invalid")
+    if payload.get("overflow"):
+        raise ValueError("joint_record_overflow")
+    raw_samples = payload.get("samples")
+    if not isinstance(raw_samples, list) or len(raw_samples) < 2:
+        raise ValueError("joint_record_samples_missing")
+
+    samples = tuple(
+        RecordedJointSample(float(item["time_s"]), _ordered_positions(item, joint_names))
+        for item in raw_samples
+        if isinstance(item, Mapping)
+    )
+    if len(samples) < 2:
+        raise ValueError("joint_record_samples_missing")
+
+    start_index = 0
+    for index, sample in enumerate(samples):
+        departure = max(abs(actual - expected) for actual, expected in zip(sample.positions_rad, start_positions_rad))
+        if departure >= departure_threshold_rad:
+            start_index = max(0, index - 1)
+            break
+
+    end_index = len(samples) - 1
+    for index in range(start_index + 1, len(samples)):
+        error = max(abs(actual - expected) for actual, expected in zip(samples[index].positions_rad, final_positions_rad))
+        if error <= final_tolerance_rad:
+            end_index = index
+            break
+
+    selected = samples[start_index : end_index + 1]
+    if len(selected) < 2:
+        raise ValueError("joint_record_motion_window_too_small")
+    duration = max(0.0, selected[-1].time_s - selected[0].time_s)
+    travel = 0.0
+    previous = selected[0].positions_rad
+    for sample in selected[1:]:
+        travel += sum(abs(first - second) for first, second in zip(previous, sample.positions_rad))
+        previous = sample.positions_rad
+    final_error = max(abs(actual - expected) for actual, expected in zip(selected[-1].positions_rad, final_positions_rad))
+    return JointMotionAnalysis(duration, travel, final_error, selected)
+
+
+def load_joint_state_record(path: Path | str) -> Mapping[str, Any]:
+    target = Path(path).expanduser().resolve()
+    try:
+        payload = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise SimulationPlatformError("joint_state_measurement_invalid") from exc
+    if not isinstance(payload, Mapping):
+        raise SimulationPlatformError("joint_state_measurement_invalid")
+    return payload
+
+
+class MoveItFkMetricBridge:
+    """Convert measured joint-state samples into measured TCP path metrics."""
+
+    def __init__(
+        self,
+        runner: RosCommandRunner,
+        *,
+        work_dir: Path | str = "~/.devagent/physical-simulation/fk-metrics",
+        timeout_s: float = 10.0,
+        max_samples: int = 500,
+        planning_frame: str = "base_link",
+        link_name: str = "tool0",
+    ) -> None:
+        if timeout_s <= 0 or max_samples < 2:
+            raise ValueError("fk_metric_bridge_limits_invalid")
+        if not planning_frame.strip() or not link_name.strip():
+            raise ValueError("fk_metric_bridge_identity_invalid")
+        self.runner = runner
+        self.work_dir = Path(work_dir).expanduser().resolve()
+        self.timeout_s = float(timeout_s)
+        self.max_samples = int(max_samples)
+        self.planning_frame = planning_frame
+        self.link_name = link_name
+
+    @staticmethod
+    def _downsample(samples: Sequence[RecordedJointSample], limit: int) -> tuple[RecordedJointSample, ...]:
+        if len(samples) <= limit:
+            return tuple(samples)
+        indices = {round(index * (len(samples) - 1) / (limit - 1)) for index in range(limit)}
+        return tuple(samples[index] for index in sorted(indices))
+
+    def compute(
+        self,
+        *,
+        motion_hash: str,
+        joint_names: tuple[str, ...],
+        samples: Sequence[RecordedJointSample],
+        target_positions_rad: tuple[float, ...],
+    ) -> FkMetricReceipt:
+        selected = self._downsample(samples, self.max_samples)
+        if len(selected) < 2:
+            raise SimulationPlatformError("fk_metric_samples_insufficient")
+        self.work_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "joint_names": list(joint_names),
+            "samples": [{"time_s": item.time_s, "positions_rad": list(item.positions_rad)} for item in selected],
+            "target_positions_rad": list(target_positions_rad),
+            "planning_frame": self.planning_frame,
+            "link_name": self.link_name,
+        }
+        input_path = self.work_dir / f"{motion_hash}.fk.json"
+        temporary = input_path.with_suffix(input_path.suffix + ".tmp")
+        temporary.write_text(json.dumps(payload, sort_keys=True, separators=(",", ":"), allow_nan=False), encoding="utf-8")
+        temporary.replace(input_path)
+        helper = Path(__file__).with_name("fk_probe.py").resolve()
+        result = self.runner.run(
+            ("python3", str(helper), "--input", str(input_path), "--timeout", format(self.timeout_s, ".6g")),
+            timeout_s=max(self.timeout_s * (len(selected) + 2), self.timeout_s + 10.0),
+        )
+        try:
+            output = json.loads(result.stdout.strip().splitlines()[-1])
+        except (IndexError, json.JSONDecodeError) as exc:
+            raise SimulationPlatformError("fk_probe_output_invalid") from exc
+        if not result.ok or not isinstance(output, dict) or not output.get("success"):
+            code = str(output.get("code")) if isinstance(output, dict) else "fk_probe_failed"
+            raise SimulationPlatformError(f"fk_metric_collection_failed:{code}")
+        return FkMetricReceipt(
+            True,
+            str(output["code"]),
+            float(output["path_length_m"]),
+            float(output["final_tcp_error_m"]),
+            int(output["sample_count"]),
+            str(output["link_name"]),
+            str(output["planning_frame"]),
+        )

devagent_physical_engine/ros2/moveit_scene.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+from pathlib import Path
+from typing import Any
+
+from ..simulation_platform import SimulationPlatformError
+from ..twin_materialization import CanonicalTwinMaterialization
+from .commands import RosCommandRunner
+
+
+@dataclass(frozen=True, slots=True)
+class MoveItSceneReceipt:
+    verified: bool
+    code: str
+    materialization_hash: str
+    twin_hash: str
+    expected_scene_hash: str
+    observed_scene_hash: str | None
+    planning_frame: str
+    expected_object_count: int
+    observed_object_count: int | None
+
+    def __post_init__(self) -> None:
+        if not self.code.strip():
+            raise ValueError("moveit_scene_receipt_code_required")
+        if len(self.materialization_hash) != 64 or len(self.twin_hash) != 64:
+            raise ValueError("moveit_scene_receipt_hash_invalid")
+        if len(self.expected_scene_hash) != 64:
+            raise ValueError("moveit_scene_receipt_scene_hash_invalid")
+        if self.observed_scene_hash is not None and len(self.observed_scene_hash) != 64:
+            raise ValueError("moveit_scene_receipt_observed_hash_invalid")
+        if not self.planning_frame.strip():
+            raise ValueError("moveit_scene_receipt_planning_frame_required")
+        if self.expected_object_count < 0:
+            raise ValueError("moveit_scene_receipt_object_count_invalid")
+        if self.observed_object_count is not None and self.observed_object_count < 0:
+            raise ValueError("moveit_scene_receipt_object_count_invalid")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class MoveItSceneBridge:
+    """Apply canonical Twin collision geometry to MoveIt and read it back."""
+
+    def __init__(
+        self,
+        runner: RosCommandRunner,
+        *,
+        work_dir: Path | str = "~/.devagent/physical-simulation/materialized-scenes",
+        timeout_s: float = 20.0,
+    ) -> None:
+        if timeout_s <= 0:
+            raise ValueError("moveit_scene_timeout_must_be_positive")
+        self.runner = runner
+        self.work_dir = Path(work_dir).expanduser().resolve()
+        self.timeout_s = float(timeout_s)
+
+    def apply_and_verify(
+        self, materialization: CanonicalTwinMaterialization
+    ) -> MoveItSceneReceipt:
+        self.work_dir.mkdir(parents=True, exist_ok=True)
+        payload_path = self.work_dir / f"{materialization.fingerprint}.moveit-scene.json"
+        temporary = payload_path.with_suffix(payload_path.suffix + ".tmp")
+        temporary.write_text(
+            json.dumps(
+                materialization.moveit_scene_payload(),
+                sort_keys=True,
+                separators=(",", ":"),
+                allow_nan=False,
+            ),
+            encoding="utf-8",
+        )
+        temporary.replace(payload_path)
+        helper = Path(__file__).with_name("scene_probe.py").resolve()
+        result = self.runner.run(
+            (
+                "python3",
+                str(helper),
+                "apply-verify",
+                "--input",
+                str(payload_path),
+                "--timeout",
+                format(self.timeout_s, ".6g"),
+            ),
+            timeout_s=self.timeout_s + 10.0,
+        )
+        try:
+            output = json.loads(result.stdout.strip().splitlines()[-1])
+        except (IndexError, json.JSONDecodeError) as exc:
+            raise SimulationPlatformError("moveit_scene_probe_output_invalid") from exc
+        if not isinstance(output, dict):
+            raise SimulationPlatformError("moveit_scene_probe_output_invalid")
+        code = str(output.get("code") or "moveit_scene_probe_failed")
+        verified = bool(output.get("success")) and result.ok
+        receipt = MoveItSceneReceipt(
+            verified=verified,
+            code=code,
+            materialization_hash=materialization.fingerprint,
+            twin_hash=materialization.twin_hash,
+            expected_scene_hash=materialization.scene_hash,
+            observed_scene_hash=(
+                str(output["observed_scene_hash"])
+                if output.get("observed_scene_hash") is not None
+                else None
+            ),
+            planning_frame=materialization.planning_frame,
+            expected_object_count=len(materialization.objects),
+            observed_object_count=(
+                int(output["observed_object_count"])
+                if output.get("observed_object_count") is not None
+                else None
+            ),
+        )
+        if not receipt.verified:
+            raise SimulationPlatformError(f"moveit_scene_verification_failed:{receipt.code}")
+        if receipt.observed_scene_hash != receipt.expected_scene_hash:
+            raise SimulationPlatformError("moveit_scene_hash_mismatch")
+        return receipt