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

devagent_physical_engine/ros2/preexecution.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..physical_motion import PhysicalMotionPlan
+from ..preexecution_contract import PreExecutionVerification
+from ..simulation_platform import SimulationPlatformError
+from ..twin_materialization import CanonicalTwinMaterialization
+from .commands import RosCommandRunner
+
+
+class MoveItPreExecutionVerifier:
+    """Fail-closed sampled collision verification for an exact motion hash.
+
+    This v0.10 verifier is deliberately *not* continuous collision checking. Its
+    receipt carries that limitation so adapter qualification cannot silently
+    upgrade it to commissioning-grade evidence.
+    """
+
+    def __init__(
+        self,
+        runner: RosCommandRunner,
+        *,
+        work_dir: Path | str = "~/.devagent/physical-simulation/preexecution",
+        timeout_s: float = 10.0,
+        max_joint_step_rad: float = 0.03,
+        max_samples: int = 4000,
+        planning_group: str = "ur_manipulator",
+    ) -> None:
+        if timeout_s <= 0 or max_joint_step_rad <= 0 or max_samples <= 1:
+            raise ValueError("preexecution_verifier_limits_invalid")
+        if not planning_group.strip():
+            raise ValueError("preexecution_planning_group_required")
+        self.runner = runner
+        self.work_dir = Path(work_dir).expanduser().resolve()
+        self.timeout_s = float(timeout_s)
+        self.max_joint_step_rad = float(max_joint_step_rad)
+        self.max_samples = int(max_samples)
+        self.planning_group = planning_group
+
+    def verify(
+        self,
+        *,
+        motion: PhysicalMotionPlan,
+        materialization: CanonicalTwinMaterialization,
+    ) -> PreExecutionVerification:
+        if motion.twin_hash != materialization.twin_hash:
+            raise SimulationPlatformError("preexecution_twin_hash_mismatch")
+        self.work_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "motion_hash": motion.fingerprint,
+            "twin_hash": motion.twin_hash,
+            "materialization_hash": materialization.fingerprint,
+            "motion": motion.to_dict(),
+        }
+        input_path = self.work_dir / f"{motion.fingerprint}.state-validity.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("state_validity_probe.py").resolve()
+        result = self.runner.run(
+            (
+                "python3",
+                str(helper),
+                "check",
+                "--input",
+                str(input_path),
+                "--timeout",
+                format(self.timeout_s, ".6g"),
+                "--max-joint-step",
+                format(self.max_joint_step_rad, ".8g"),
+                "--max-samples",
+                str(self.max_samples),
+                "--group",
+                self.planning_group,
+            ),
+            timeout_s=max(self.timeout_s * max(2, min(self.max_samples, 100)), self.timeout_s + 10.0),
+        )
+        try:
+            output = json.loads(result.stdout.strip().splitlines()[-1])
+        except (IndexError, json.JSONDecodeError) as exc:
+            raise SimulationPlatformError("preexecution_probe_output_invalid") from exc
+        if not isinstance(output, dict):
+            raise SimulationPlatformError("preexecution_probe_output_invalid")
+        verified = bool(output.get("success")) and result.ok
+        code = str(output.get("code") or "preexecution_probe_failed")
+        failure_codes = () if verified else (code,)
+        evidence: dict[str, Any] = {
+            key: output.get(key)
+            for key in (
+                "evidence_hash",
+                "first_invalid",
+                "group_name",
+                "max_joint_step_rad",
+            )
+            if key in output
+        }
+        return PreExecutionVerification(
+            verified=verified,
+            method="moveit_get_state_validity_discrete_v1",
+            motion_hash=motion.fingerprint,
+            twin_hash=motion.twin_hash,
+            materialization_hash=materialization.fingerprint,
+            continuous_collision_check=False,
+            sample_count=int(output.get("sample_count") or 0),
+            failure_codes=failure_codes,
+            evidence=evidence,
+        )

devagent_physical_engine/ros2/qualification.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from hashlib import sha256
+
+from ..physical_motion import JointTrajectoryPoint, PhysicalMotionPlan
+from ..trajectory_qualification import TrajectoryQualificationCase
+from ..twin import TwinSpec
+from .ur5e_adapter import UR5E_JOINTS
+
+
+REFERENCE_GRAPH_HASH = sha256(
+    b"devagent-v0.9-ur5e-trajectory-runtime-reference-corpus"
+).hexdigest()
+UR5E_REFERENCE_START = (0.0, -1.57, 0.0, -1.57, 0.0, 0.0)
+
+
+def ur5e_trajectory_runtime_twin() -> TwinSpec:
+    """A robot-only identity twin used strictly for trajectory-runtime qualification.
+
+    It is intentionally not a Level-2/3 cell twin and must never be used to make
+    environment, collision, physics, or commissioning claims.
+    """
+
+    return TwinSpec(
+        twin_id="TWIN-UR5E-TRAJECTORY-RUNTIME-V1",
+        robot_profile_key="ur5e",
+        robot_base_pose=None,
+        entities=(),
+        source_entity_id="runtime_probe_source",
+        destination_entity_id="runtime_probe_destination",
+        workpiece_entity_id=None,
+        metadata={"qualification_scope": "trajectory_runtime_only"},
+    )
+
+
+def _motion(
+    twin: TwinSpec,
+    *,
+    motion_id: str,
+    points: tuple[tuple[float, ...], ...],
+) -> PhysicalMotionPlan:
+    timeline = tuple(
+        JointTrajectoryPoint(positions, float(index) * 4.0)
+        for index, positions in enumerate(points)
+    )
+    return PhysicalMotionPlan(
+        motion_id=motion_id,
+        robot_profile_key="ur5e",
+        joint_names=UR5E_JOINTS,
+        points=timeline,
+        source_graph_hash=REFERENCE_GRAPH_HASH,
+        planner_id="devagent-reference-trajectory-v1",
+        twin_hash=twin.fingerprint,
+        constraints=("simulation_only", "trajectory_runtime_qualification"),
+        metadata={"customer_plan": False, "environment_qualification": False},
+    )
+
+
+def ur5e_trajectory_runtime_cases(
+    twin: TwinSpec,
+) -> tuple[TrajectoryQualificationCase, ...]:
+    plus = (0.15, -1.45, 0.10, -1.45, 0.10, 0.10)
+    minus = (-0.15, -1.65, -0.10, -1.65, -0.10, -0.10)
+    motions = (
+        _motion(twin, motion_id="UR5E-RUNTIME-001", points=(UR5E_REFERENCE_START, plus)),
+        _motion(twin, motion_id="UR5E-RUNTIME-002", points=(UR5E_REFERENCE_START, minus)),
+        _motion(
+            twin,
+            motion_id="UR5E-RUNTIME-003",
+            points=(UR5E_REFERENCE_START, plus, minus, UR5E_REFERENCE_START),
+        ),
+    )
+    return tuple(
+        TrajectoryQualificationCase(
+            case_id=f"UR5E-TRAJECTORY-{index:03d}",
+            motion=motion,
+            reset_state={"initial_joint_positions_rad": list(UR5E_REFERENCE_START)},
+            max_tracking_error_rad=0.05,
+        )
+        for index, motion in enumerate(motions, start=1)
+    )

devagent_physical_engine/ros2/qualification_v10.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any
+
+from ..physical_motion import JointTrajectoryPoint, PhysicalMotionPlan
+from ..twin import (
+    ControllerModel,
+    EvidenceOrigin,
+    EvidenceValue,
+    GeometryKind,
+    GeometrySpec,
+    PhysicsSpec,
+    Pose3D,
+    ToolSpec,
+    TwinEntity,
+    TwinSpec,
+)
+from .commands import SubprocessRosRunner
+from .ur5e_adapter import UR5E_JOINTS
+from .ur5e_v10_adapter import UR5eCanonicalTwinAdapter
+
+
+_REFERENCE_GRAPH_HASH = sha256(b"devagent-v0.10-canonical-twin-reference-corpus").hexdigest()
+_REFERENCE_START = (0.0, -1.57, 0.0, -1.57, 0.0, 0.0)
+
+
+def _pose(x: float, y: float, z: float, *, origin: EvidenceOrigin = EvidenceOrigin.MEASURED) -> Pose3D:
+    return Pose3D(x, y, z, origin=origin, frame_id="world")
+
+
+def _box(x: float, y: float, z: float, *, origin: EvidenceOrigin = EvidenceOrigin.IMPORTED) -> GeometrySpec:
+    return GeometrySpec(GeometryKind.BOX, origin, dimensions_m=(x, y, z), collision_geometry=True)
+
+
+def ur5e_canonical_reference_twin() -> TwinSpec:
+    """Level-3-like reference Twin for canonical environment/runtime qualification."""
+    source = TwinEntity("reference_source", "fixture", _pose(2.0, 0.0, 0.4), _box(1.0, 0.8, 0.8))
+    destination = TwinEntity("reference_destination", "fixture", _pose(2.0, 1.2, 0.4), _box(1.0, 0.8, 0.8))
+    workpiece = TwinEntity(
+        "reference_workpiece",
+        "workpiece",
+        _pose(2.0, 0.0, 0.825),
+        _box(0.20, 0.10, 0.05),
+        physics=PhysicsSpec(
+            mass_kg=EvidenceValue(1.0, EvidenceOrigin.MEASURED, source_ref="v0.10-reference"),
+            friction_coefficient=EvidenceValue(0.5, EvidenceOrigin.MEASURED, source_ref="v0.10-reference"),
+            restitution=EvidenceValue(0.0, EvidenceOrigin.MEASURED, source_ref="v0.10-reference"),
+        ),
+    )
+    return TwinSpec(
+        twin_id="TWIN-UR5E-CANONICAL-V10-REFERENCE",
+        robot_profile_key="ur5e",
+        robot_base_pose=_pose(0.0, 0.0, 0.0),
+        entities=(source, destination, workpiece),
+        source_entity_id=source.entity_id,
+        destination_entity_id=destination.entity_id,
+        workpiece_entity_id=workpiece.entity_id,
+        tool=ToolSpec(
+            tool_id="reference_tool",
+            tcp=_pose(0.0, 0.0, 0.0),
+            geometry=_box(0.01, 0.01, 0.01, origin=EvidenceOrigin.ROBOT_PROFILE),
+            max_payload_kg=EvidenceValue(5.0, EvidenceOrigin.ROBOT_PROFILE),
+        ),
+        controller=ControllerModel(speed_scale_pct=EvidenceValue(100.0, EvidenceOrigin.MEASURED)),
+        metadata={
+            "qualification_scope": "canonical_twin_materialization_runtime_only",
+            "customer_plan": False,
+            "site_qualification": False,
+        },
+    )
+
+
+def _motion(twin: TwinSpec, *, motion_id: str, points: tuple[tuple[float, ...], ...]) -> PhysicalMotionPlan:
+    trajectory = tuple(
+        JointTrajectoryPoint(positions_rad=positions, time_from_start_s=float(index) * 4.0)
+        for index, positions in enumerate(points)
+    )
+    return PhysicalMotionPlan(
+        motion_id=motion_id,
+        robot_profile_key="ur5e",
+        joint_names=UR5E_JOINTS,
+        points=trajectory,
+        source_graph_hash=_REFERENCE_GRAPH_HASH,
+        planner_id="devagent-v10-reference-trajectory",
+        twin_hash=twin.fingerprint,
+        constraints=("simulation_only", "canonical_twin_scope_qualification"),
+        metadata={"customer_plan": False, "workpiece_manipulation": False},
+    )
+
+
+def ur5e_canonical_reference_motions(twin: TwinSpec) -> tuple[PhysicalMotionPlan, ...]:
+    plus = (0.12, -1.47, 0.08, -1.47, 0.08, 0.08)
+    minus = (-0.12, -1.67, -0.08, -1.67, -0.08, -0.08)
+    return (
+        _motion(twin, motion_id="UR5E-V10-CANONICAL-001", points=(_REFERENCE_START, plus)),
+        _motion(twin, motion_id="UR5E-V10-CANONICAL-002", points=(_REFERENCE_START, minus)),
+        _motion(twin, motion_id="UR5E-V10-CANONICAL-003", points=(_REFERENCE_START, plus, minus, _REFERENCE_START)),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class CanonicalQualificationCaseResult:
+    motion_hash: str
+    success: bool
+    failure_code: str | None
+    metrics: dict[str, Any]
+    state: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class CanonicalQualificationReport:
+    run_id: str
+    scope: str
+    adapter_id: str
+    twin_hash: str
+    total_cases: int
+    passed_cases: int
+    promotion_candidate: bool
+    physical_qualification: bool
+    commissioning_qualification: bool
+    continuous_collision_check: bool
+    minimum_clearance_measured: bool
+    results: tuple[CanonicalQualificationCaseResult, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            **asdict(self),
+            "real_execution_allowed": False,
+            "site_qualification": False,
+            "results": [item.to_dict() for item in self.results],
+        }
+
+
+def run_ur5e_canonical_qualification(
+    runner,
+    *,
+    ros_setup: Path | str = "/opt/ros/jazzy/setup.bash",
+    log_dir: Path | str = "~/.devagent/v10-canonical-qualification",
+    startup_timeout_s: float = 120.0,
+) -> CanonicalQualificationReport:
+    twin = ur5e_canonical_reference_twin()
+    motions = ur5e_canonical_reference_motions(twin)
+    adapter = UR5eCanonicalTwinAdapter(
+        runner,
+        ros_setup=ros_setup,
+        log_dir=log_dir,
+        startup_timeout_s=startup_timeout_s,
+    )
+    results: list[CanonicalQualificationCaseResult] = []
+    try:
+        adapter.prepare(twin=twin)
+        for index, motion in enumerate(motions, start=1):
+            failure: str | None = None
+            try:
+                adapter.reset(
+                    case_id=f"UR5E-V10-{index:03d}",
+                    state={"initial_joint_positions_rad": list(_REFERENCE_START)},
+                )
+                metrics = adapter.execute_motion(motion=motion)
+                state = dict(adapter.capture_state())
+                preexecution = state.get("preexecution") or {}
+                environment_ok = all(
+                    bool((state.get(key) or {}).get("verified"))
+                    for key in ("frame_alignment", "gazebo_world", "moveit_scene")
+                )
+                measured_ok = all(
+                    value is not None
+                    for value in (
+                        metrics.observed_duration_s,
+                        metrics.measured_joint_travel_rad,
+                        metrics.path_length_m,
+                        metrics.final_tcp_error_m,
+                    )
+                )
+                passed = metrics.success and environment_ok and measured_ok and bool(preexecution.get("verified"))
+                if not passed:
+                    failure = "canonical_scope_evidence_incomplete"
+            except Exception as exc:
+                passed = False
+                metrics = None
+                state = {}
+                failure = f"canonical_scope_error:{type(exc).__name__}"
+
+            results.append(CanonicalQualificationCaseResult(
+                motion_hash=motion.fingerprint,
+                success=passed,
+                failure_code=failure,
+                metrics=metrics.to_dict() if metrics is not None else {},
+                state=state,
+            ))
+    finally:
+        adapter.stop()
+
+    passed_cases = sum(item.success for item in results)
+    promotion_candidate = bool(results) and passed_cases == len(results)
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    return CanonicalQualificationReport(
+        run_id=f"canonical-twin-{timestamp}",
+        scope="canonical_twin_runtime_experimental",
+        adapter_id=adapter.descriptor.adapter_id,
+        twin_hash=twin.fingerprint,
+        total_cases=len(results),
+        passed_cases=passed_cases,
+        promotion_candidate=promotion_candidate,
+        physical_qualification=False,
+        commissioning_qualification=False,
+        continuous_collision_check=False,
+        minimum_clearance_measured=False,
+        results=tuple(results),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m devagent_physical_engine.ros2.qualification_v10")
+    parser.add_argument("--ros-setup", default="/opt/ros/jazzy/setup.bash")
+    parser.add_argument("--workspace-setup", default=None)
+    parser.add_argument("--log-dir", default="~/.devagent/v10-canonical-qualification")
+    parser.add_argument("--report", default=None)
+    parser.add_argument("--startup-timeout", type=float, default=120.0)
+    args = parser.parse_args(argv)
+
+    runner = SubprocessRosRunner(ros_setup=args.ros_setup, workspace_setup=args.workspace_setup)
+    report = run_ur5e_canonical_qualification(
+        runner,
+        ros_setup=args.ros_setup,
+        log_dir=args.log_dir,
+        startup_timeout_s=args.startup_timeout,
+    )
+    payload = report.to_dict()
+    report_path = (
+        Path(args.report).expanduser().resolve()
+        if args.report
+        else Path(args.log_dir).expanduser().resolve() / "latest-canonical-twin.json"
+    )
+    report_path.parent.mkdir(parents=True, exist_ok=True)
+    report_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(payload, indent=2))
+    print(f"Canonical Twin qualification report: {report_path}")
+    return 0 if report.promotion_candidate else 7
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devagent_physical_engine/ros2/scene_probe.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import argparse
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _canon_float(value: float) -> float:
+    value = float(value)
+    if abs(value) < 1e-12:
+        return 0.0
+    return float(format(value, ".12g"))
+
+
+def _hash(payload: object) -> str:
+    text = json.dumps(payload, sort_keys=True, separators=(",", ":"), allow_nan=False)
+    return sha256(text.encode("utf-8")).hexdigest()
+
+
+def _canonical_scene(planning_frame: str, objects: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "planning_frame": planning_frame,
+        "objects": [
+            {
+                "id": item["id"],
+                "geometry_kind": item["geometry_kind"],
+                "dimensions_m": [_canon_float(value) for value in item["dimensions_m"]],
+                "position_m": [_canon_float(value) for value in item["position_m"]],
+                "quaternion_xyzw": [_canon_float(value) for value in item["quaternion_xyzw"]],
+            }
+            for item in sorted(objects, key=lambda value: value["id"])
+        ],
+    }
+
+
+def _qmul(first, second):
+    ax, ay, az, aw = first
+    bx, by, bz, bw = second
+    return (
+        aw * bx + ax * bw + ay * bz - az * by,
+        aw * by - ax * bz + ay * bw + az * bx,
+        aw * bz + ax * by - ay * bx + az * bw,
+        aw * bw - ax * bx - ay * by - az * bz,
+    )
+
+
+def _qconj(quaternion):
+    return (-quaternion[0], -quaternion[1], -quaternion[2], quaternion[3])
+
+
+def _qrot(quaternion, vector):
+    result = _qmul(_qmul(quaternion, (vector[0], vector[1], vector[2], 0.0)), _qconj(quaternion))
+    return result[:3]
+
+
+def _combine_pose(parent, child):
+    parent_q = (parent.orientation.x, parent.orientation.y, parent.orientation.z, parent.orientation.w)
+    child_q = (child.orientation.x, child.orientation.y, child.orientation.z, child.orientation.w)
+    rotated = _qrot(parent_q, (child.position.x, child.position.y, child.position.z))
+    position = (
+        parent.position.x + rotated[0],
+        parent.position.y + rotated[1],
+        parent.position.z + rotated[2],
+    )
+    return position, _qmul(parent_q, child_q)
+
+
+def _wait_future(node, future, timeout_s: float) -> bool:
+    import rclpy
+    rclpy.spin_until_future_complete(node, future, timeout_sec=float(timeout_s))
+    return future.done()
+
+
+def apply_verify(path: Path, timeout_s: float) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    planning_frame = str(payload["planning_frame"])
+    expected_hash = str(payload["scene_hash"])
+    expected_objects = list(payload["objects"])
+
+    import rclpy
+    from geometry_msgs.msg import Pose
+    from moveit_msgs.msg import CollisionObject, PlanningScene, PlanningSceneComponents
+    from moveit_msgs.srv import ApplyPlanningScene, GetPlanningScene
+    from shape_msgs.msg import SolidPrimitive
+
+    rclpy.init()
+    node = rclpy.create_node("devagent_scene_probe")
+    apply_client = node.create_client(ApplyPlanningScene, "/apply_planning_scene")
+    get_client = node.create_client(GetPlanningScene, "/get_planning_scene")
+    try:
+        if not apply_client.wait_for_service(timeout_sec=timeout_s):
+            return {"success": False, "code": "apply_planning_scene_unavailable"}
+        if not get_client.wait_for_service(timeout_sec=timeout_s):
+            return {"success": False, "code": "get_planning_scene_unavailable"}
+
+        scene = PlanningScene()
+        scene.is_diff = True
+        for item in expected_objects:
+            collision = CollisionObject()
+            collision.header.frame_id = planning_frame
+            collision.id = str(item["id"])
+            primitive = SolidPrimitive()
+            dimensions = [float(value) for value in item["dimensions_m"]]
+            kind = str(item["geometry_kind"])
+            if kind == "box":
+                primitive.type = SolidPrimitive.BOX
+                primitive.dimensions = dimensions
+            elif kind == "cylinder":
+                primitive.type = SolidPrimitive.CYLINDER
+                primitive.dimensions = [dimensions[1], dimensions[0]]
+            else:
+                return {"success": False, "code": f"unsupported_geometry:{kind}"}
+
+            pose_data = item["pose"]
+            position = pose_data["position_m"]
+            quaternion = pose_data["quaternion_xyzw"]
+            pose = Pose()
+            pose.position.x = float(position[0])
+            pose.position.y = float(position[1])
+            pose.position.z = float(position[2])
+            pose.orientation.x = float(quaternion[0])
+            pose.orientation.y = float(quaternion[1])
+            pose.orientation.z = float(quaternion[2])
+            pose.orientation.w = float(quaternion[3])
+            collision.pose = pose
+            identity = Pose()
+            identity.orientation.w = 1.0
+            collision.primitives = [primitive]
+            collision.primitive_poses = [identity]
+            collision.operation = CollisionObject.ADD
+            scene.world.collision_objects.append(collision)
+
+        apply_request = ApplyPlanningScene.Request()
+        apply_request.scene = scene
+        future = apply_client.call_async(apply_request)
+        if not _wait_future(node, future, timeout_s):
+            return {"success": False, "code": "apply_planning_scene_timeout"}
+        response = future.result()
+        if response is None or not response.success:
+            return {"success": False, "code": "apply_planning_scene_rejected"}
+
+        request = GetPlanningScene.Request()
+        request.components.components = PlanningSceneComponents.WORLD_OBJECT_GEOMETRY
+        future = get_client.call_async(request)
+        if not _wait_future(node, future, timeout_s):
+            return {"success": False, "code": "get_planning_scene_timeout"}
+        response = future.result()
+        if response is None:
+            return {"success": False, "code": "get_planning_scene_empty"}
+
+        expected_ids = {str(item["id"]) for item in expected_objects}
+        observed: list[dict[str, Any]] = []
+        for collision in response.scene.world.collision_objects:
+            if collision.id not in expected_ids:
+                continue
+            if collision.header.frame_id != planning_frame:
+                return {
+                    "success": False,
+                    "code": f"scene_planning_frame_mismatch:{collision.id}:{collision.header.frame_id}",
+                }
+            if len(collision.primitives) != 1 or len(collision.primitive_poses) != 1:
+                return {"success": False, "code": f"scene_shape_invalid:{collision.id}"}
+            primitive = collision.primitives[0]
+            primitive_pose = collision.primitive_poses[0]
+            position, quaternion = _combine_pose(collision.pose, primitive_pose)
+            if primitive.type == SolidPrimitive.BOX:
+                kind = "box"
+                dimensions = list(primitive.dimensions)
+            elif primitive.type == SolidPrimitive.CYLINDER:
+                kind = "cylinder"
+                dimensions = [
+                    primitive.dimensions[SolidPrimitive.CYLINDER_RADIUS],
+                    primitive.dimensions[SolidPrimitive.CYLINDER_HEIGHT],
+                ]
+            else:
+                return {"success": False, "code": f"scene_shape_unsupported:{collision.id}"}
+            observed.append({
+                "id": collision.id,
+                "geometry_kind": kind,
+                "dimensions_m": dimensions,
+                "position_m": list(position),
+                "quaternion_xyzw": list(quaternion),
+            })
+
+        observed_scene = _canonical_scene(planning_frame, observed)
+        observed_hash = _hash(observed_scene)
+        missing = sorted(expected_ids - {item["id"] for item in observed})
+        success = not missing and len(observed) == len(expected_objects) and observed_hash == expected_hash
+        return {
+            "success": success,
+            "code": "moveit_scene_readback_verified" if success else "moveit_scene_readback_mismatch",
+            "observed_scene_hash": observed_hash,
+            "observed_object_count": len(observed),
+            "missing_object_ids": missing,
+        }
+    finally:
+        node.destroy_node()
+        rclpy.shutdown()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    apply = sub.add_parser("apply-verify")
+    apply.add_argument("--input", required=True)
+    apply.add_argument("--timeout", type=float, default=20.0)
+    args = parser.parse_args()
+    try:
+        result = apply_verify(Path(args.input).expanduser().resolve(), float(args.timeout))
+    except Exception as exc:
+        result = {"success": False, "code": f"moveit_scene_probe_error:{type(exc).__name__}"}
+    print(json.dumps(result, sort_keys=True))
+    return 0 if result.get("success") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())