#!/usr/bin/env python3 """Validate the current PartSpec/SoftwareSpec v2 contracts; never launch Kit or load weights.""" from __future__ import annotations import argparse import hashlib import json import math from pathlib import Path from jsonschema import Draft202012Validator ROOT = Path(__file__).resolve().parents[1] SCHEMAS = ROOT / "docs/schemas" ENTITY_AXES = {"joint": "Jmax", "actuator": "Amax", "end_effector": "Emax", "sensor": "Smax"} PART_TYPES = {"leg", "arm", "hand", "gripper", "torso", "neck", "head", "mobile_base", "sensor", "other"} SENSOR_KINDS = {"joint_state", "contact_normal", "wrench", "imu", "camera", "tactile", "lidar", "other"} EFFECTOR_ROLES = {"support", "tool", "fingertip", "grasp", "gaze", "sensor_mount", "other"} def _finite_float(text): value = float(text) if not math.isfinite(value): raise ValueError(f"Non-finite JSON number: {text}") return value def _finite_int(text): value = int(text) try: finite = math.isfinite(value) except OverflowError as error: raise ValueError("JSON integer exceeds finite physical numeric range") from error if not finite: raise ValueError("Non-finite JSON integer") return value def _reject_constant(text): raise ValueError(f"Non-standard JSON constant: {text}") def _unique_object(pairs): result = {} for key, value in pairs: if key in result: raise ValueError(f"Duplicate JSON key: {key}") result[key] = value return result def read_json(path): return json.loads( Path(path).read_text(encoding="utf-8"), parse_float=_finite_float, parse_int=_finite_int, parse_constant=_reject_constant, object_pairs_hook=_unique_object, ) def _structure(path, schema_name): data = read_json(path) schema = read_json(SCHEMAS / schema_name) Draft202012Validator.check_schema(schema) error = next(Draft202012Validator(schema).iter_errors(data), None) if error is not None: location = ".".join(str(part) for part in error.absolute_path) or "" raise ValueError(f"{path}: {location}: {error.message}") return data def _version(path): data = read_json(path) if not isinstance(data, dict) or type(data.get("schema_version")) is not int: raise ValueError("schema_version must be a JSON integer in an object") if data["schema_version"] != 2: raise ValueError( "Only schema_version=2 is supported; migrate legacy leg bundles with migrate_leg_description.py" ) return data["schema_version"] def _integers(data, fields): # JSON Schema considers 1.0 an integer; the Python contracts require int. for field in fields: if field in data and type(data[field]) is not int: raise ValueError(f"{field} must be a JSON integer, not a decimal/bool") def _indexed(records, field="id"): result = {item[field]: item for item in records} if len(result) != len(records): raise ValueError(f"Duplicate {field} in entity collection") return result def _source_path(root, relative): root = Path(root).expanduser().resolve() if not (root / relative).resolve().is_relative_to(root): raise ValueError("Source asset path must remain inside source root") def validate_hardware(path): _version(path) data = _structure(path, "part_spec.v2.schema.json") _validate_part(data) return data def _joint_semantics(joint): if not math.isclose(math.hypot(*joint["origin"]["quat_xyzw"]), 1.0, abs_tol=1e-5): raise ValueError("Joint origin quaternion must be normalized xyzw") fixed = joint["type"] == "fixed" expected_unit = None if fixed else ("m" if joint["type"] == "prismatic" else "rad") if joint["position_unit"] != expected_unit or (joint["actuation"] == "fixed") != fixed: raise ValueError("Joint type, actuation and position unit disagree") if fixed: if joint["axis"] is not None or joint["limits"] is not None: raise ValueError("Fixed joints must not have moving axes/limits") elif joint["axis"] is None or not math.isclose(math.hypot(*joint["axis"]), 1.0, abs_tol=1e-5): raise ValueError("Moving joint axis must be a unit vector") if (joint["coupling"] is not None) != (joint["actuation"] == "coupled"): raise ValueError("Coupled joints require an explicit coupling, other joints forbid it") limits = joint["limits"] if not fixed and joint["limits_origin"] == "declared" and limits is None: raise ValueError("Declared moving joint limits cannot be missing") if limits is not None: position = limits["position"] if joint["type"] == "continuous": if position is not None: raise ValueError("Continuous joints cannot have bounded position limits") elif position is None or not position[0] < position[1]: raise ValueError("Bounded joint position limits require lower < upper") def _tree_semantics(topology, joints): bodies, root = set(topology["bodies"]), topology["root_body"] if root not in bodies: raise ValueError("Missing topology root body") parents = {} for joint in joints.values(): _joint_semantics(joint) parent, child = joint["parent"], joint["child"] if parent not in bodies or child not in bodies or parent == child or child == root or child in parents: raise ValueError("Invalid body reference or multiple parents in spanning tree") parents[child] = parent if set(parents) != bodies - {root}: raise ValueError("Disconnected body in spanning tree") for body in bodies: seen = set() while body != root: if body in seen: raise ValueError("Cyclic spanning tree; use explicit loop constraints instead") seen.add(body) body = parents[body] if (topology["structure"] == "closed_chain") != bool(topology["constraints"]): raise ValueError("Closed chains require explicit loop constraints; trees forbid them") def _coupling_semantics(joints): for name, joint in joints.items(): coupling = joint["coupling"] if coupling is None: continue target = joints.get(coupling["joint_id"]) if ( target is None or target["type"] == "fixed" or target["position_unit"] != joint["position_unit"] or coupling["multiplier"] == 0 ): raise ValueError("Coupling references an incompatible joint") seen, current = {name}, target while current["coupling"] is not None: if current["id"] in seen: raise ValueError("Cyclic joint coupling") seen.add(current["id"]) next_id = current["coupling"]["joint_id"] if next_id not in joints: raise ValueError("Missing coupling joint") current = joints[next_id] def _actuator_semantics(actuators, joints): driven = [] for actuator in actuators.values(): joint = joints.get(actuator["joint_id"]) if joint is None or joint["actuation"] != "active": raise ValueError("Actuator must drive one active joint, not a passive/coupled/fixed joint") driven.append(joint["id"]) linear = joint["type"] == "prismatic" units = {"position_pd": "m" if linear else "rad", "position": "m" if linear else "rad"} units.update(velocity="m/s" if linear else "rad/s", effort="N" if linear else "N*m") for mode, command in actuator["commands"].items(): if command["unit"] != units[mode]: raise ValueError("Actuator command unit disagrees with joint type/mode") if (command["gains"] is not None) != (mode == "position_pd"): raise ValueError("Only position_pd requires explicit PD gains") limits = joint["limits"] if ( limits and limits["position"] and not limits["position"][0] <= actuator["neutral_position"] <= limits["position"][1] ): raise ValueError("Actuator neutral position outside hard limits") active = {joint["id"] for joint in joints.values() if joint["actuation"] == "active"} if len(set(driven)) != len(driven) or set(driven) != active: raise ValueError("Require exactly one independent actuator per active joint") def _validate_part(data): source = data["source"] if data["description_role"] == "asset_reference": _source_path(source["root"], source["path"]) topology = data["topology"] joints = _indexed(topology["joints"]) if len({joint["source_name"] for joint in joints.values()}) != len(joints): raise ValueError("Duplicate source joint names") _tree_semantics(topology, joints) _coupling_semantics(joints) frames = _indexed(data["frames"]) if data["root_frame"] not in frames or frames[data["root_frame"]]["body"] != topology["root_body"]: raise ValueError("Root frame must belong to root body") if data["attachment"]["frame_id"] not in frames: raise ValueError("Missing attachment frame") parent_transform = data["attachment"].get("source_parent_transform") if parent_transform is not None and not math.isclose(math.hypot(*parent_transform["quat_xyzw"]), 1.0, abs_tol=1e-5): raise ValueError("Source parent transform quaternion must be normalized xyzw") for frame in frames.values(): if frame["body"] not in topology["bodies"]: raise ValueError("Frame references missing body") if not math.isclose(math.hypot(*frame["quat_xyzw"]), 1.0, abs_tol=1e-5): raise ValueError("Frame quaternion must be normalized xyzw") for constraint in _indexed(topology["constraints"]).values(): if constraint["parent_frame"] not in frames or constraint["child_frame"] not in frames: raise ValueError("Loop constraint references missing frame") if frames[constraint["parent_frame"]]["body"] == frames[constraint["child_frame"]]["body"]: raise ValueError("Loop constraint must connect different bodies") _actuator_semantics(_indexed(data["actuators"]), joints) effectors = _indexed(data["end_effectors"]) for effector in effectors.values(): if effector["frame_id"] not in frames: raise ValueError("End effector references missing frame") if effector["contact"] is not None: _integers(effector["contact"], ("source_collision_index",)) targets = {"part": {data["part_id"]}, "joint": set(joints), "end_effector": set(effectors)} for sensor in _indexed(data["sensors"]).values(): if sensor["frame_id"] not in frames or not set(sensor["target"]["ids"]) <= targets[sensor["target"]["entity"]]: raise ValueError("Sensor references missing frame/target") if sensor["kind"] == "joint_state" and sensor["target"]["entity"] != "joint": raise ValueError("Joint-state sensor must explicitly target joints") if sensor["kind"] == "contact_normal" and set(sensor["outputs"]) != {"contact.normal_force"}: raise ValueError("Normal-contact sensors cannot advertise a full wrench or friction output") prefixes = { "joint_state": "joint.", "wrench": "contact.wrench", "imu": "imu.", "camera": "image.", "lidar": "range.", } prefix = prefixes.get(sensor["kind"]) if prefix is not None and any(not signal.startswith(prefix) for signal in sensor["outputs"]): raise ValueError("Sensor output semantics disagree with sensor kind") timing = data["timing"] if timing["physics_dt_s"] is not None: ratio = timing["control_dt_s"] / timing["physics_dt_s"] if not math.isfinite(ratio) or ratio < 1 or not math.isclose(ratio, round(ratio), abs_tol=1e-8): raise ValueError("Control dt must be an integer multiple of physics dt") if data["safety"]["command_timeout_s"] < timing["control_dt_s"]: raise ValueError("Command timeout must not be shorter than one control step") def _repo_file(root, relative): path = (root / relative).resolve() if not path.is_relative_to(root): raise ValueError(f"Path escapes repository: {relative}") if not path.is_file(): raise FileNotFoundError(path) return path def _artifact(data, root): checkpoint = data["artifact"]["checkpoint"] if checkpoint is not None: weights = _repo_file(root, checkpoint["path"]) with weights.open("rb") as stream: actual = hashlib.file_digest(stream, "sha256").hexdigest() if actual != checkpoint["sha256"]: raise ValueError("Checkpoint SHA256 mismatch") def _bindings(data, root): bindings = data["hardware_bindings"] ids = [item["part_id"] for item in bindings] if len(set(ids)) != len(ids): raise ValueError("Duplicate hardware part_id bindings") hardware = [] for binding in bindings: part = validate_hardware(_repo_file(root, binding["spec_path"])) if part["part_id"] != binding["part_id"]: raise ValueError("Hardware binding part_id mismatch") hardware.append(part) return hardware def _entities(part): return { "part": [{"id": part["part_id"]}], "joint": [joint for joint in part["topology"]["joints"] if joint["type"] != "fixed"], "actuator": part["actuators"], "end_effector": part["end_effectors"], "sensor": part["sensors"], } def _select(port, entities): records = entities[port["entity"]] selector, values = port["selector"]["type"], set(port["selector"]["values"]) if selector == "all": if values: raise ValueError("all selector must have empty values") return records if not values: raise ValueError("Explicit selectors require nonempty values") if selector == "ids": if not values <= {record["id"] for record in records}: raise ValueError("Port selector references missing entity ID") return [record for record in records if record["id"] in values] if selector == "sensor_output": if port["entity"] != "sensor": raise ValueError("sensor_output selector requires sensor entity") return [record for record in records if values <= set(record["outputs"])] field, expected = ("role", "end_effector") if selector == "role" else ("kind", "sensor") if port["entity"] != expected: raise ValueError("role/sensor_kind selector used on incompatible entity") return [record for record in records if record[field] in values] def _port_structure(port, ports, capacities): shape, entity = port["shape"], port["entity"] prefix = ["B"] if entity == "part" else ["B", ENTITY_AXES[entity]] if shape[: len(prefix)] != prefix or any(type(dim) is not int or dim < 1 for dim in shape[len(prefix) :]): raise ValueError("Port shape must use B and its entity capacity axis followed by positive integer dimensions") if entity != "part" and capacities[ENTITY_AXES[entity]] == 0: raise ValueError("Declared port has zero entity capacity; omit it from this profile") if port["representation"] == "features": if not port["features"] or len(shape) != len(prefix) + 1 or shape[-1] != len(port["features"]): raise ValueError("Feature port dimension must exactly match ordered features") _indexed(port["features"], "name") elif port["features"]: raise ValueError("Opaque tensor ports must not claim scalar feature layouts") if port["kind"] == "mask": if port["dtype"] != "bool" or shape != prefix or port["mask"] is not None or port["representation"] != "tensor": raise ValueError("Entity masks require bool [B,capacity], no features or nested mask") if port["direction"] != "input": raise ValueError("Entity masks are adapter-provided input ports") elif entity != "part": mask = ports.get(port["mask"]) if mask is None or mask["kind"] != "mask" or mask["entity"] != entity or mask["selector"] != port["selector"]: raise ValueError("Entity port requires a matching selector/entity mask") elif port["mask"] is not None: raise ValueError("Part-level ports must not use entity masks") if port["kind"] == "command": if port["direction"] != "output" or entity != "actuator" or port["command"] is None: raise ValueError("Commands must be explicit actuator output ports") if port["dtype"] != "float32" or port["representation"] != "features" or len(port["features"]) != 1: raise ValueError("Scalar actuator commands require one float32 feature per actuator") command = port["command"] if command["encoding"] == "normalized": if command["clip"] != [-1, 1] or port["features"][0]["unit"] != "1": raise ValueError("Normalized commands require dimensionless [-1,1] execution clip") elif command["clip"] is not None and command["clip"][0] >= command["clip"][1]: raise ValueError("Physical command clip requires lower < upper") elif port["command"] is not None: raise ValueError("Non-command ports must not contain command metadata") def _requirements(requirements, part): for field, allowed in ( ("part_types", PART_TYPES), ("required_sensor_kinds", SENSOR_KINDS), ("required_effector_roles", EFFECTOR_ROLES), ): if not set(requirements[field]) <= allowed: raise ValueError(f"Unknown requirement in {field}") if part["part_type"] not in requirements["part_types"]: raise ValueError("Software does not support this part type") if ( part["topology"]["structure"] not in requirements["topologies"] or part["attachment"]["mode"] not in requirements["attachment_modes"] ): raise ValueError("Unsupported topology or attachment mode") entities = _entities(part) if not {joint["type"] for joint in entities["joint"]} <= set(requirements["joint_types"]): raise ValueError("Unsupported joint type") if not requirements["supports_coupling"] and any(joint["coupling"] for joint in entities["joint"]): raise ValueError("Software does not support coupled joints") for entity, axis in ENTITY_AXES.items(): if len(entities[entity]) > requirements["capacities"][axis]: raise ValueError(f"Hardware exceeds {axis} capacity") if not set(requirements["required_sensor_kinds"]) <= {sensor["kind"] for sensor in part["sensors"]}: raise ValueError("Missing required sensor capability") outputs = {output for sensor in part["sensors"] for output in sensor["outputs"]} if not set(requirements["required_sensor_outputs"]) <= outputs: raise ValueError("Missing required sensor output semantics") if not set(requirements["required_effector_roles"]) <= {effector["role"] for effector in part["end_effectors"]}: raise ValueError("Missing required end-effector role") for actuator in part["actuators"]: if not set(requirements["required_control_modes"]) <= set(actuator["commands"]): raise ValueError("Missing required actuator control mode") if requirements["required_control_modes"] and not part["actuators"]: raise ValueError("Control software requires actuators") return entities def _signal_coverage(port, selected, entities): if port["kind"] != "state" or port["representation"] != "features": return for feature in port["features"]: quantity = feature["quantity"] if quantity in ("joint.position", "joint.velocity"): dynamic_unit = "joint_position" if quantity == "joint.position" else "joint_velocity" for record in selected: if port["entity"] != "joint": raise ValueError("Joint-state quantities require joint entity ports") physical_unit = record["position_unit"] + ("/s" if quantity == "joint.velocity" else "") expected = (dynamic_unit, physical_unit) if feature["normalization"] == "identity" else ("1",) if feature["unit"] not in expected: raise ValueError("Joint-state feature unit/normalization disagrees with selected joints") if not quantity.startswith(("joint.", "contact.")): continue covered = set() for sensor in entities["sensor"]: if sensor["target"]["entity"] != port["entity"]: continue if any(quantity == signal or quantity.startswith(signal + ".") for signal in sensor["outputs"]): covered.update(sensor["target"]["ids"]) if not {record["id"] for record in selected} <= covered: raise ValueError(f"State port {port['name']} lacks sensor coverage for {quantity}") def _port_binding(port, selected, commanded, entities): if port["required"] and not selected: raise ValueError(f"Required port {port['name']} selects no entities") _signal_coverage(port, selected, entities) if port["kind"] != "command": return mode = port["command"]["mode"] for actuator in selected: if actuator["id"] in commanded: raise ValueError("Conflicting command ports target the same actuator") commanded.add(actuator["id"]) if mode not in actuator["commands"]: raise ValueError("Command port mode unavailable on selected actuator") unit = port["features"][0]["unit"] if port["command"]["encoding"] == "physical" and unit not in ( "actuator_command", actuator["commands"][mode]["unit"], ): raise ValueError("Physical command port unit disagrees with selected actuator") def _software_contract(data, root): requirements, interface = data["requirements"], data["interface"] _integers(requirements["capacities"], ENTITY_AXES.values()) _integers(interface, ("contract_version",)) ports = _indexed(interface["ports"], "name") for port in ports.values(): _port_structure(port, ports, requirements["capacities"]) parts = _bindings(data, root) for part in parts: entities = _requirements(requirements, part) commanded = set() for port in ports.values(): _port_binding(port, _select(port, entities), commanded, entities) timing = data["runtime"]["timing"] steps = [part["timing"]["control_dt_s"] for part in parts] if timing["policy"] == "per_part": if timing["control_dt_s"] is not None: raise ValueError("per_part timing must not declare a single common control dt") elif any(not math.isclose(step, steps[0], rel_tol=0, abs_tol=1e-12) for step in steps): raise ValueError("Software requires common control dt across alternative bindings") elif timing["control_dt_s"] is not None and not math.isclose( timing["control_dt_s"], steps[0], rel_tol=0, abs_tol=1e-12 ): raise ValueError("Software/hardware control dt mismatch") runtime = data["runtime"] if runtime["implementation"] == "available": raise ValueError("No v2 runtime adapters are registered yet; do not claim availability") if runtime["adapter_id"] is not None: raise ValueError("Unimplemented runtime must not advertise a callable adapter") def validate_software(path, repo_root=ROOT, require_runtime=False): _version(path) data = _structure(path, "software_spec.v2.schema.json") root = Path(repo_root).resolve() _software_contract(data, root) if require_runtime: raise ValueError("v2 description is compatible, but its runtime adapter is unimplemented") _artifact(data, root) return data def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--hardware", type=Path, nargs="+", default=[]) parser.add_argument("--software", type=Path, nargs="+", default=[]) parser.add_argument("--repo-root", type=Path, default=ROOT) parser.add_argument( "--require-runtime", action="store_true", help="Reject compatible but unimplemented software adapters" ) args = parser.parse_args(argv) if not args.hardware and not args.software: parser.error("Provide --hardware and/or --software") try: for path in args.hardware: validate_hardware(path) print(f"Hardware description OK: {path}") for path in args.software: validate_software(path, args.repo_root, args.require_runtime) print(f"Software description and bindings OK: {path} (v2 runtime unimplemented)") except (ValueError, OSError) as error: parser.exit(1, f"Description validation failed: {error}\n") print("Static descriptions only; simulation, checkpoint contents and trained-skill quality are NOT verified.") if __name__ == "__main__": main()