"""Body-part independent v2 contracts: static capability matching, not simulation claims.""" import copy import hashlib import importlib.util import json import shutil from pathlib import Path import pytest import tomllib from jsonschema import Draft202012Validator ROOT = Path(__file__).resolve().parents[1] def module(name, relative): spec = importlib.util.spec_from_file_location(name, ROOT / relative) result = importlib.util.module_from_spec(spec) spec.loader.exec_module(result) return result validator = module("part_validator", "scripts/validate_descriptions.py") examples = module("part_examples", "scripts/examples/generate_part_descriptions.py") migration = module("part_migration", "scripts/migrate_leg_description.py") def save(path, data): path.parent.mkdir(parents=True, exist_ok=True) path.write_text(json.dumps(data, allow_nan=False), encoding="utf-8") return path def replace(data, dotted, value): keys = dotted.split(".") current = data for key in keys[:-1]: current = current[int(key)] if isinstance(current, list) else current[key] current[int(keys[-1]) if isinstance(current, list) else keys[-1]] = value @pytest.fixture def repo(tmp_path): root = tmp_path / "repo" shutil.copytree(ROOT / "configs", root / "configs") return root @pytest.fixture def software(repo): return validator.read_json(repo / "configs/software/part_position_control.json") @pytest.mark.parametrize("name", ["part_spec.v2.schema.json", "software_spec.v2.schema.json"]) def test_v2_schemas(name): Draft202012Validator.check_schema(validator.read_json(ROOT / "docs/schemas" / name)) @pytest.mark.parametrize("path", sorted((ROOT / "configs/parts").glob("*.json")), ids=lambda path: path.stem) def test_different_body_parts_use_same_schema(path): data = validator.validate_hardware(path) assert data["schema_version"] == 2 and data["kind"] == "robot_part" assert data["description_role"] == ("asset_reference" if path.stem == "go2_fl" else "design_template") @pytest.mark.parametrize("name", ["part_position_control", "wheel_velocity_control", "part_rgb_perception"]) def test_software_profiles(name): data = validator.validate_software(ROOT / f"configs/software/{name}.json") assert data["runtime"]["implementation"] == "unimplemented" assert data["artifact"]["trained_skill"] is False def test_examples_are_deterministic_and_explicitly_synthetic(): for relative, expected in examples.build_examples().items(): assert validator.read_json(ROOT / relative) == expected if relative.startswith("configs/parts/"): assert expected["source"]["format"] == "design" assert expected["extensions"]["skillfactory.example"]["not_manufacturer_data"] is True def test_variable_dof_actuation_and_effector_counts(): hand = validator.validate_hardware(ROOT / "configs/parts/example_hand.json") entities = validator._entities(hand) assert [len(entities[name]) for name in ("joint", "actuator", "end_effector")] == [4, 2, 2] assert hand["topology"]["joints"][1]["coupling"]["joint_id"] == "joint_0" pod = validator.validate_hardware(ROOT / "configs/parts/example_sensor.json") entities = validator._entities(pod) assert all(not entities[name] for name in ("joint", "actuator", "end_effector")) assert len(entities["sensor"]) == 2 torso = validator.validate_hardware(ROOT / "configs/parts/example_torso.json") assert torso["end_effectors"] == [] @pytest.mark.parametrize( ("field", "value"), [ ("schema_version", 2.0), ("typo", True), ("source.path", "fake_factory_asset.urdf"), ("topology.root_body", "missing"), ("topology.joints.0.parent", "link_5"), ("topology.joints.0.position_unit", "m"), ("topology.joints.0.axis", [0, 0, 0]), ("topology.joints.0.axis", [1e200, 0, 0]), ("topology.joints.0.origin.quat_xyzw", [0, 0, 0, 0]), ("topology.joints.0.limits.position", [1, -1]), ("topology.joints.0.limits", None), ("topology.joints.0.actuation", "passive"), ("frames.0.body", "missing"), ("frames.0.quat_xyzw", [0, 0, 0, 2]), ("attachment.frame_id", "missing"), ("actuators.0.neutral_position", 2), ("actuators.0.commands.position_pd.unit", "m"), ("actuators.0.commands.position_pd.gains", None), ("end_effectors.0.frame_id", "missing"), ("end_effectors.0.contact", {"source_collision_index": 0.0, "gap_method": "sphere"}), ("sensors.0.target.ids", ["missing"]), ("timing.control_dt_s", 0.003), ("safety.command_timeout_s", 0.005), ("extensions", {"unnamespaced": {}}), ], ) def test_invalid_part_semantics(tmp_path, field, value): data = validator.read_json(ROOT / "configs/parts/example_arm.json") replace(data, field, value) with pytest.raises(ValueError): validator.validate_hardware(save(tmp_path / "part.json", data)) def test_actuator_coverage_and_duplicate_names(tmp_path): data = validator.read_json(ROOT / "configs/parts/example_arm.json") data["actuators"].pop() with pytest.raises(ValueError, match="one independent actuator"): validator.validate_hardware(save(tmp_path / "part.json", data)) data = validator.read_json(ROOT / "configs/parts/example_arm.json") data["actuators"].append(copy.deepcopy(data["actuators"][0])) with pytest.raises(ValueError, match="Duplicate"): validator.validate_hardware(save(tmp_path / "part.json", data)) data = validator.read_json(ROOT / "configs/parts/example_arm.json") data["topology"]["joints"][1]["source_name"] = "joint_0" with pytest.raises(ValueError, match="source joint names"): validator.validate_hardware(save(tmp_path / "part.json", data)) def test_coupling_cycles_rejected(tmp_path): data = validator.read_json(ROOT / "configs/parts/example_hand.json") data["topology"]["joints"][1]["coupling"]["joint_id"] = "joint_3" data["topology"]["joints"][3]["coupling"]["joint_id"] = "joint_1" with pytest.raises(ValueError, match="Cyclic joint coupling"): validator.validate_hardware(save(tmp_path / "part.json", data)) def test_explicit_closed_chain_frames_not_a_cyclic_tree(tmp_path): data = validator.read_json(ROOT / "configs/parts/example_arm.json") data["topology"]["structure"] = "closed_chain" data["topology"]["constraints"] = [ {"id": "loop", "type": "loop_closure", "parent_frame": "root", "child_frame": "tool_frame"} ] assert validator.validate_hardware(save(tmp_path / "part.json", data))["topology"]["structure"] == "closed_chain" data["topology"]["constraints"][0]["child_frame"] = "missing" with pytest.raises(ValueError, match="Loop constraint"): validator.validate_hardware(save(tmp_path / "part.json", data)) @pytest.mark.parametrize( ("field", "value"), [ ("requirements.capacities.Jmax", 3), ("requirements.capacities.Amax", 1), ("requirements.capacities.Emax", 1), ("requirements.capacities.Smax", 1), ("requirements.capacities.Amax", 32.0), ("requirements.supports_coupling", False), ("requirements.joint_types", ["revolute"]), ("requirements.required_control_modes", ["effort"]), ("requirements.required_sensor_kinds", ["wrench"]), ("requirements.required_effector_roles", ["tool"]), ("interface.ports.3.shape", ["B", "Jmax", 1]), ("interface.ports.3.mask", "joint_mask"), ("interface.ports.3.command.clip", [-2, 2]), ("interface.ports.3.features.0.unit", "rad"), ("interface.ports.1.features.0.unit", "m"), ("interface.ports.1.features.0.unit", "degree"), ("interface.ports.1.features.1.name", "position"), ("interface.ports.1.shape", ["B", "Jmax", 3]), ("runtime.implementation", "available"), ("runtime.adapter_id", "imaginary_adapter"), ("artifact.trained_skill", True), ], ) def test_software_binding_and_port_rejections(tmp_path, repo, software, field, value): replace(software, field, value) with pytest.raises(ValueError): validator.validate_software(save(tmp_path / "software.json", software), repo) def test_overlapping_command_ports_rejected(tmp_path, repo, software): command = copy.deepcopy(software["interface"]["ports"][3]) command["name"] = "conflicting_command" software["interface"]["ports"].append(command) with pytest.raises(ValueError, match="Conflicting command ports"): validator.validate_software(save(tmp_path / "software.json", software), repo) def test_per_part_timing_and_explicit_common_control_contract(tmp_path, repo, software): path = repo / "configs/parts/example_arm.json" data = validator.read_json(path) data["timing"]["control_dt_s"] = 0.02 save(path, data) target = save(tmp_path / "software.json", software) assert validator.validate_software(target, repo)["runtime"]["timing"]["policy"] == "per_part" software["runtime"]["timing"]["policy"] = "common_control_dt" with pytest.raises(ValueError, match="common control dt"): validator.validate_software(save(target, software), repo) data["timing"].update(control_dt_s=0.01, physics_dt_s=0.005) save(path, data) software["runtime"]["timing"]["control_dt_s"] = 0.01 assert validator.validate_software(save(target, software), repo) def test_joint_sensor_coverage_is_per_entity_not_just_kind(tmp_path, repo, software): path = repo / "configs/parts/example_hand.json" data = validator.read_json(path) data["sensors"][0]["target"]["ids"] = ["joint_0"] save(path, data) with pytest.raises(ValueError, match="sensor coverage"): validator.validate_software(save(tmp_path / "software.json", software), repo) def test_camera_requires_rgb_semantics_not_just_camera_kind(tmp_path, repo): path = repo / "configs/parts/example_sensor.json" data = validator.read_json(path) data["sensors"][0]["outputs"] = ["image.depth_m"] save(path, data) with pytest.raises(ValueError, match="sensor output semantics"): validator.validate_software(ROOT / "configs/software/part_rgb_perception.json", repo) def test_normal_force_cannot_satisfy_wrench_observation(tmp_path, software): software["hardware_bindings"] = software["hardware_bindings"][:1] force = copy.deepcopy(software["interface"]["ports"][-1]) force.update(name="force", kind="state", required=True, frame="entity") force["features"] = [examples.feature(axis, "contact.normal_force." + axis, "N") for axis in ("x", "y", "z")] software["interface"]["ports"].append(force) path = save(tmp_path / "software.json", software) assert validator.validate_software(path) force["features"][0]["quantity"] = "contact.wrench.fx" with pytest.raises(ValueError, match="sensor coverage"): validator.validate_software(save(path, software)) def test_version_boundaries_and_require_runtime(tmp_path, repo, software): software["hardware_bindings"][0]["spec_path"] = "configs/legs/go2_fl.json" with pytest.raises(ValueError, match="Only schema_version=2"): validator.validate_software(save(tmp_path / "software.json", software), repo) with pytest.raises(ValueError, match="adapter is unimplemented"): validator.validate_software(ROOT / "configs/software/part_position_control.json", require_runtime=True) def test_selector_preserves_hardware_order_not_requested_id_order(): data = validator.validate_hardware(ROOT / "configs/parts/example_arm.json") selector = {"entity": "actuator", "selector": {"type": "ids", "values": ["drive_joint_2", "drive_joint_0"]}} records = validator._select(selector, validator._entities(data)) assert [item["id"] for item in records] == ["drive_joint_0", "drive_joint_2"] def test_migration_preserves_actuator_order_fixed_branches_and_mount(tmp_path): controls = [{"name": name, "q_default": 0.1, "action_scale": 0.25, "kp": 25, "kd": 0.5} for name in ("knee", "hip")] spec = { "schema_version": 1, "part_id": "test_leg", "source_root": str(tmp_path / "source"), "urdf": "robot.urdf", "package_name": "test", "license_file": "LICENSE", "license_id": "test", "mount_joint": "hip", "auxiliary_root_joints": [], "joints": controls, "foot_body": "toe", "foot_collision_index": 0, "physics_dt": 0.002, "decimation": 5, "soft_limit_factor": 0.9, } tree = [ { "name": name, "type": kind, "parent": parent, "child": child, "axis": [0, 1, 0], "xyz": [0, 0, 0], "rpy": [0, 0, 0], } for name, kind, parent, child in ( ("hip", "revolute", "anchor_base", "thigh"), ("knee", "revolute", "thigh", "calf"), ("toe_joint", "fixed", "calf", "toe"), ) ] bundle = { "schema_version": 2, "kind": "single_leg", "spec": spec, "tree": tree, "anchor_body": "anchor_base", "joint_order": ["knee", "hip"], "links": {"thigh": None, "calf": None, "toe": None}, "joints": [ {"name": item["name"], "limits": {"lower": -1, "upper": 1, "velocity": 10, "effort": 10}} for item in controls ], "source": {"commit": None, "sha256": "0" * 64}, "derived_urdf_sha256": "1" * 64, "mount": {"source_parent": "trunk", "source_parent_T_anchor": {"xyz": [0.1, 0.2, 0.3], "rpy": [0, 0, 0]}}, "foot": {"body": "toe", "type": "sphere"}, "length_scale_m": 0.5, "known_mass_scale_kg": 0.2, } result = migration.part_from_leg_bundle(bundle) validator.validate_hardware(save(tmp_path / "part.json", result)) assert [item["joint_id"] for item in result["actuators"]] == ["knee", "hip"] assert [item["id"] for item in result["topology"]["joints"]] == ["hip", "knee", "toe_joint"] assert result["attachment"]["source_parent_transform"]["xyz"] == [0.1, 0.2, 0.3] assert result["source"]["sha256"] == "0" * 64 @pytest.mark.parametrize("text", ['{"a": 1, "a": 2}', '{"a": NaN}', '{"a": Infinity}', '{"a": 1e999}']) def test_invalid_json_values(tmp_path, text): path = tmp_path / "invalid.json" path.write_text(text) with pytest.raises(ValueError): validator.read_json(path) def test_checkpoint_hash_without_loading_weights(tmp_path, software, repo): weights = repo / "sampling_policy.pt" payload = b"Static validation does not deserialize this fixture." weights.write_bytes(payload) software["artifact"]["format"] = "torch_save_state_dict" software["artifact"]["checkpoint"] = {"path": weights.name, "sha256": hashlib.sha256(payload).hexdigest()} path = save(tmp_path / "software.json", software) assert validator.validate_software(path, repo)["artifact"]["trained_skill"] is False weights.write_bytes(b"tampered") with pytest.raises(ValueError, match="SHA256"): validator.validate_software(path, repo) @pytest.mark.parametrize("invalid", ["id", "duplicate", "missing", "escape"]) def test_invalid_cross_file_bindings(tmp_path, software, repo, invalid): if invalid == "id": software["hardware_bindings"][0]["part_id"] = "wrong" elif invalid == "duplicate": software["hardware_bindings"][1]["part_id"] = "go2_fl" elif invalid == "missing": (repo / "configs/parts/go2_fl.json").unlink() else: path = repo / "configs/parts/go2_fl.json" path.unlink() path.symlink_to(ROOT / "configs/parts/go2_fl.json") with pytest.raises((ValueError, OSError)): validator.validate_software(save(tmp_path / "software.json", software), repo) def test_cli_success_and_failure(tmp_path, capsys): validator.main(["--software", str(ROOT / "configs/software/part_position_control.json")]) assert "NOT verified" in capsys.readouterr().out with pytest.raises(SystemExit) as error: validator.main(["--hardware", str(tmp_path / "missing.json")]) assert error.value.code == 1 def test_release_has_only_latest_description_specs(): assert {path.name for path in (ROOT / "docs/schemas").glob("*.json")} == { "part_spec.v2.schema.json", "software_spec.v2.schema.json", } assert not (ROOT / "docs/legacy_single_leg_spec.md").exists() assert not (ROOT / "configs/software/leg_skill.json").exists() assert validator.read_json(ROOT / "configs/legs/go2_fl.json")["schema_version"] == 1 # runtime input retained version = tomllib.loads((ROOT / "source/SkillFactory/config/extension.toml").read_text())["package"]["version"] assert version == "0.0.2" assert (ROOT / "README.md").read_text().startswith(f"# SkillFactory v{version}\n") for path in (ROOT / "configs/software").glob("*.json"): data = validator.read_json(path) assert data["schema_version"] == 2 and data["software_version"] == version