lockwire 0.2.0__py3-none-any.whl

lockwire/start_operation.py

@@ -0,0 +1,92 @@
+"""The shared contract-only start operation; desktop callers never generate HTML."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from lockwire.edit import _contract_lock, contract_revision, relative_source
+from lockwire.scene import SceneRefusal
+from lockwire.scene_urdf import _resolve_mesh_path, mesh_root
+from lockwire.schema import ArtifactRef, Contract, RobotInfo, save_contract
+from lockwire.sdf import parse_sdf
+from lockwire.urdf import _refuse_doctype_entity, parse_urdf
+
+
+def _find_meshes(root: ET.Element, source: Path, target: Path) -> tuple[list[ArtifactRef], str]:
+    """The model's mesh files as sha256-pinned refs inside the robot's package folder.
+
+    All-or-nothing: the scene loader refuses a mesh it cannot verify, so a partial list
+    would break the whole scene. Anything missing or outside the package comes back as a note.
+    """
+    uris = sorted({u for m in root.iter("mesh") if (u := m.get("filename") or m.findtext("uri"))})
+    folder, found, problems = mesh_root(source, target.parent), {}, []
+    for uri in uris:
+        try:
+            path = _resolve_mesh_path(uri, source.parent, source, (source.parent, folder)).resolve()
+            found[path.relative_to(folder).as_posix()] = path
+        except (SceneRefusal, ValueError):
+            problems.append(uri)
+    if problems:
+        return [], (f"{len(problems)} of {len(uris)} mesh files not found inside the robot's package folder "
+                    f"(e.g. {problems[0]}); the 3D model is not recorded.")
+    refs = [ArtifactRef(path=rel, sha256=hashlib.sha256(p.read_bytes()).hexdigest())
+            for rel, p in sorted(found.items())]
+    return refs, ""
+
+
+def start_contract(
+    urdf: Path | str,
+    *,
+    out: Path | str | None = None,
+    overwrite: bool = False,
+    expected_revision: str | None = None,
+) -> dict[str, str | bool]:
+    """Create once, or replace only the exact bytes the caller observed."""
+    source = Path(urdf).resolve()
+    target = Path(out).resolve() if out is not None else source.parent / "lockwire.yaml"
+    if source == target:
+        raise ValueError("model and lockfile paths must differ")
+    with _contract_lock(target):
+        exists = target.exists()
+        if exists and not overwrite:
+            return {"path": str(target), "revision": contract_revision(target), "written": False}
+        if overwrite and (
+            not exists or expected_revision is None or expected_revision != contract_revision(target)
+        ):
+            raise ValueError("lockfile changed since it was opened; reload before overwriting")
+        raw = source.read_bytes()
+        _refuse_doctype_entity(raw, source)
+        xml = ET.fromstring(raw)
+        model = parse_sdf(source) if xml.tag == "sdf" else parse_urdf(source)
+        spelling = relative_source(target, source)
+        meshes, note = _find_meshes(xml, source, target)
+        model = model.model_copy(update={
+            "external_assets": meshes,
+            "source": spelling,
+            "provenance": model.provenance.model_copy(update={"source": spelling}),
+        })
+        contract = Contract(robot=RobotInfo(name=source.stem), model=model)
+        fd, temporary = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+        os.close(fd)
+        try:
+            save_contract(contract, Path(temporary))
+            # Refuse even a non-cooperating writer that changed bytes during parsing.
+            if exists and contract_revision(target) != expected_revision:
+                raise ValueError("lockfile changed since it was opened; reload before overwriting")
+            if exists:
+                os.replace(temporary, target)
+            else:
+                # Installing a new file must never replace a writer racing this start.
+                try:
+                    os.link(temporary, target)
+                except FileExistsError as exc:
+                    raise ValueError("lockfile appeared during start; open it before overwriting") from exc
+        finally:
+            Path(temporary).unlink(missing_ok=True)
+        done: dict[str, str | bool] = {
+            "path": str(target), "revision": contract_revision(target), "written": True}
+        return {**done, "note": note} if note else done

lockwire/statics.py

@@ -0,0 +1,77 @@
+"""Rigid-body statics for stage one — support reactions, determinate sets only.
+
+``docs/design/e5_solver_choice.md`` chose **numpy-stiffness** by
+measurement. This module is the *determinate subset* of that choice, and the
+narrowing is deliberate, not a substitution:
+
+* For a **statically determinate** support set the reactions follow from
+  equilibrium alone and are **independent of the stiffness EI**. The solver study measured
+  exactly that — its ``equilibrium-statics`` candidate matched the textbook
+  reactions to 1.9e-16 — and rejected it only because it cannot produce
+  *deflections* or answer a *redundant* set.
+* For a **redundant** set the reactions *do* depend on EI. The contract schema
+  is frozen and declares no Young's modulus, no section and no area on
+  ``Link`` or ``Physical``, so there is nothing to solve a redundant set with.
+  Those read NOT SCORED naming why, never a plausible-looking guess.
+
+Consequently a stiffness solve has no input it could consume here, and a beam
+deflection is not offered at all. What that document lists as unproven —
+plates, shear-dominated stubby members, out-of-plane frames, dynamics — is
+likewise out of stage one and named in the payload rather than omitted.
+
+Sign convention: reactions are positive upward, against gravity acting along
+the root frame's -Z. Positions are scalars on one horizontal span axis.
+"""
+
+from __future__ import annotations
+
+STANDARD_G = 9.81
+"""m/s^2. The same standard-gravity figure preflight's cross-signal stage
+scores an accelerometer's |g| against (``preflight/stages/cross_signal.py``);
+kept literal here so this module imports no preflight stage."""
+
+
+class Indeterminate(ValueError):
+    """The support set cannot be answered from the contract alone."""
+
+
+def weight_n(mass_kg: float, g: float = STANDARD_G) -> float:
+    """Weight in newtons of a mass in kilograms."""
+    return mass_kg * g
+
+
+def support_reactions(
+    load_n: float, load_pos_m: float, support_pos_m: list[float]
+) -> list[tuple[float, float]]:
+    """Reaction (force N, moment N*m) at each support, in the order given.
+
+    One support is a fixed interface: it carries the whole load plus the moment
+    ``W * (load_pos - support)`` — case 1 in reaction form.
+
+    Two supports are the lever rule — case 3, the two-bolt bracket. Each
+    is a simple support, so each carries force and no moment; a support behind
+    the load correctly comes out negative (it pulls down).
+
+    Three or more supports on one rigid body are statically indeterminate: the
+    split depends on stiffness the contract does not declare. Raises
+    ``Indeterminate`` rather than returning a number.
+    """
+    count = len(support_pos_m)
+    if count == 0:
+        raise Indeterminate("no mount point is declared, so nothing reacts the load")
+    if count == 1:
+        return [(load_n, load_n * (load_pos_m - support_pos_m[0]))]
+    if count == 2:
+        near, far = support_pos_m
+        if near == far:
+            raise Indeterminate(
+                "both mount points sit at the same place on the span axis, "
+                "so the load split between them is undetermined"
+            )
+        reaction_far = load_n * (load_pos_m - near) / (far - near)
+        return [(load_n - reaction_far, 0.0), (reaction_far, 0.0)]
+    raise Indeterminate(
+        f"{count} mount points on one rigid body is statically indeterminate; the load "
+        "split depends on the structure's stiffness (Young's modulus and section), which "
+        "the contract schema does not declare"
+    )

lockwire/units.py

@@ -0,0 +1,115 @@
+"""Minimal unit handling: enough to sum and compare contract quantities.
+
+Deliberately a table, not a units library. Every unit the schema accepts is
+listed here; an unknown unit fails validation instead of passing through.
+"""
+
+import math
+
+# unit -> (dimension, factor to the dimension's base unit)
+_UNITS: dict[str, tuple[str, float]] = {
+    # mass -> kg
+    "kg": ("mass", 1.0),
+    "g": ("mass", 1e-3),
+    "mg": ("mass", 1e-6),
+    # power -> W
+    "W": ("power", 1.0),
+    "mW": ("power", 1e-3),
+    "kW": ("power", 1e3),
+    # energy -> Wh (Wh over J: battery math reads naturally)
+    "Wh": ("energy", 1.0),
+    "mWh": ("energy", 1e-3),
+    "kWh": ("energy", 1e3),
+    "J": ("energy", 1.0 / 3600.0),
+    # time -> s
+    "s": ("time", 1.0),
+    "ms": ("time", 1e-3),
+    "min": ("time", 60.0),
+    "h": ("time", 3600.0),
+    # rate -> Hz
+    "Hz": ("rate", 1.0),
+    # electrical
+    "V": ("voltage", 1.0),
+    "mV": ("voltage", 1e-3),
+    "A": ("current", 1.0),
+    "mA": ("current", 1e-3),
+    # length -> m
+    "m": ("length", 1.0),
+    "cm": ("length", 1e-2),
+    "mm": ("length", 1e-3),
+    "m^2": ("area", 1.0),
+    "m^4": ("second_moment", 1.0),
+    # temperature (absolute compare only — never summed)
+    "C": ("temperature", 1.0),
+    "degC": ("temperature", 1.0),  # bag spelling for the same Celsius scale
+    # pressure -> hPa
+    "Pa": ("pressure", 0.01),
+    "hPa": ("pressure", 1.0),
+    "kPa": ("pressure", 10.0),
+    "MPa": ("pressure", 1e4),
+    "GPa": ("pressure", 1e7),
+    # scalar angular measure -> rad (not semantic position or orientation roles)
+    "deg": ("angle", math.pi / 180.0),
+    # kinematics
+    "m/s^2": ("acceleration", 1.0),
+    "m/s": ("velocity", 1.0),
+    "rad/s": ("angular_rate", 1.0),
+    "rad/s^2": ("angular_acceleration", 1.0),
+    "rad": ("angle", 1.0),
+    "N": ("force", 1.0),
+    "N*m": ("torque", 1.0),
+    "ohm": ("resistance", 1.0),
+    "kg*m^2": ("inertia", 1.0),
+    "kg/m^3": ("density", 1.0),
+    "N/m": ("linear_stiffness", 1.0),
+    "N*m/rad": ("rotational_stiffness", 1.0),
+    "N*s/m": ("linear_damping", 1.0),
+    "N*m*s/rad": ("rotational_damping", 1.0),
+    "N/m^3": ("contact_stiffness", 1.0),
+    "N*s/m^3": ("contact_damping", 1.0),
+    "1/s": ("inverse_time", 1.0),
+    # dimensionless
+    "1": ("dimensionless", 1.0),
+    "%": ("dimensionless", 0.01),
+    # thermal resistance -> C/W (temperature C/degC stay on temperature)
+    "C/W": ("thermal_resistance", 1.0),
+    # RF power level -> dBm (logarithmic; never share power with W/mW/kW —
+    # scale-factor convert or sum of dBm and watts is arithmetic nonsense)
+    "dBm": ("power_level", 1.0),
+    # RF gain / ratio -> dB (log-space only; never convertible to a linear qty)
+    "dB": ("gain", 1.0),
+    "dBi": ("gain", 1.0),
+    # data rate -> bit/s
+    "bit/s": ("data_rate", 1.0),
+    "kbit/s": ("data_rate", 1e3),
+    "Mbit/s": ("data_rate", 1e6),
+}
+
+
+class UnitError(ValueError):
+    """Unknown unit or dimension mismatch."""
+
+
+def known(unit: str) -> bool:
+    return unit in _UNITS
+
+
+def dimension(unit: str) -> str:
+    try:
+        return _UNITS[unit][0]
+    except KeyError:
+        raise UnitError(f"unknown unit {unit!r}") from None
+
+
+def to_base(value: float, unit: str) -> float:
+    """Convert to the dimension's base unit (kg, W, Wh, s, Hz, ...)."""
+    try:
+        return value * _UNITS[unit][1]
+    except KeyError:
+        raise UnitError(f"unknown unit {unit!r}") from None
+
+
+def convert(value: float, unit: str, target: str) -> float:
+    if dimension(unit) != dimension(target):
+        raise UnitError(f"cannot convert {unit!r} to {target!r}: different dimensions")
+    return to_base(value, unit) / _UNITS[target][1]

lockwire/urdf.py

@@ -0,0 +1,348 @@
+"""URDF -> Tier A extraction (`lockwire init`). Witness W2: in-repo model files.
+
+Traps handled here (spec v3):
+- URDF inertia is about the COM in the inertial frame -> compare principal
+  moments + axes, never raw tensor elements.
+- Zero-mass / missing-inertial links are flagged, not silently accepted.
+- Structure hash covers the kinematic topology (joints + links), so a moved
+  mount or re-parented joint changes it; cosmetic reordering does not.
+- Unresolved xacro / ROS substitutions are refused — never treated as link names.
+"""
+
+import datetime as dt
+import hashlib
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from lockwire.schema import (
+    Joint,
+    JointLimits,
+    JointOrigin,
+    Link,
+    ModelRecord,
+    PrincipalInertia,
+    Provenance,
+    Quantity,
+    _model_structure_hash,
+)
+
+# `${var}` in a name is xacro property substitution (TurtleBot3 ships this unexpanded).
+# A bare `$` (e.g. link `cost_$`) is NOT matched — that would be a false positive.
+_XACRO_PROP = re.compile(r"\$\{[^}]+\}")
+# ROS command substitutions that survive only when xacro was never run.
+_ROS_SUBST = re.compile(r"\$\((?:arg|find)\b")
+_REMEDY = "Expand the xacro first, then re-run: xacro model.urdf.xacro > model.urdf"
+
+
+class UnresolvedXacroError(ValueError):
+    """Input still contains xacro/ROS substitutions; refuse rather than invent names."""
+
+
+def _local_tag(tag: str) -> str:
+    """Strip Clark notation `{ns}local` → `local`; leave un-namespaced tags alone."""
+    if tag.startswith("{") and "}" in tag:
+        return tag.split("}", 1)[1]
+    return tag
+
+
+def _refuse_unresolved_xacro(root: ET.Element, path: Path) -> None:
+    """Refuse unexpanded xacro rather than treat template tokens as robot links.
+
+    Detection order (most → least specific to the TurtleBot3 miss):
+    1. `${…}` surviving in a link or joint *name* (or parent/child link ref)
+    2. a `<xacro:…>` element or the xacro XML namespace still in the tree
+    3. `$(arg …)` / `$(find …)` in any attribute value
+
+    False-positive shape we deliberately do *not* match: a bare `$` in a name
+    (`link_$1`, `cost_usd`) — only braced `${…}` property syntax counts.
+    """
+    for el in root.findall("link"):
+        name = el.get("name") or ""
+        if _XACRO_PROP.search(name):
+            raise UnresolvedXacroError(
+                f"{path}: unresolved xacro — link name {name!r} still contains "
+                f"${{…}} substitutions. This is a xacro template, not a finished URDF. "
+                f"{_REMEDY}"
+            )
+    for el in root.findall("joint"):
+        name = el.get("name") or ""
+        if _XACRO_PROP.search(name):
+            raise UnresolvedXacroError(
+                f"{path}: unresolved xacro — joint name {name!r} still contains "
+                f"${{…}} substitutions. This is a xacro template, not a finished URDF. "
+                f"{_REMEDY}"
+            )
+        for end in ("parent", "child"):
+            ref = el.find(end)
+            link_name = ref.get("link", "") if ref is not None else ""
+            if _XACRO_PROP.search(link_name):
+                raise UnresolvedXacroError(
+                    f"{path}: unresolved xacro — joint {name!r} {end} link "
+                    f"{link_name!r} still contains ${{…}} substitutions. "
+                    f"This is a xacro template, not a finished URDF. {_REMEDY}"
+                )
+
+    for el in root.iter():
+        tag = el.tag if isinstance(el.tag, str) else ""
+        local = _local_tag(tag)
+        # Un-namespaced `xacro:foo` (common in shipped .xacro) or `{…xacro…}foo`.
+        if local.startswith("xacro:") or (
+            tag.startswith("{") and "xacro" in tag[1:].split("}", 1)[0]
+        ):
+            raise UnresolvedXacroError(
+                f"{path}: unresolved xacro — <{local}> element remains in the document. "
+                f"This is a xacro template, not a finished URDF. {_REMEDY}"
+            )
+        for attr_val in el.attrib.values():
+            if _ROS_SUBST.search(attr_val):
+                raise UnresolvedXacroError(
+                    f"{path}: unresolved xacro — $(arg …)/$(find …) substitutions remain "
+                    f"in attribute values. This is a xacro template, not a finished URDF. "
+                    f"{_REMEDY}"
+                )
+
+
+def _principal(
+    ixx: float, ixy: float, ixz: float, iyy: float, iyz: float, izz: float
+) -> PrincipalInertia:
+    tensor = np.array([[ixx, ixy, ixz], [ixy, iyy, iyz], [ixz, iyz, izz]])
+    moments, axes = np.linalg.eigh(tensor)  # ascending; columns = eigenvectors
+    return PrincipalInertia(
+        moments_kgm2=tuple(float(m) for m in moments),
+        axes=tuple(tuple(float(v) for v in axes[:, i]) for i in range(3)),
+    )
+
+
+def _parse_link(el: ET.Element) -> tuple[Link, bool]:
+    """Returns (link, is_zero_mass)."""
+    name = el.get("name", "?")
+    inertial = el.find("inertial")
+    if inertial is None:
+        return Link(name=name), True
+
+    mass_el = inertial.find("mass")
+    mass_val = float(mass_el.get("value", "0")) if mass_el is not None else 0.0
+    if mass_val == 0.0:
+        return Link(name=name), True
+
+    origin = inertial.find("origin")
+    xyz = tuple(
+        float(x) for x in (origin.get("xyz", "0 0 0") if origin is not None else "0 0 0").split()
+    )
+
+    inertia_el = inertial.find("inertia")
+    inertia = None
+    if inertia_el is not None:
+        inertia = _principal(
+            *(float(inertia_el.get(k, "0")) for k in ("ixx", "ixy", "ixz", "iyy", "iyz", "izz"))
+        )
+
+    link = Link(
+        name=name,
+        mass=Quantity(value=mass_val, unit="kg"),
+        com=xyz,
+        frame=name,  # URDF inertial origin is expressed in the link frame
+        inertia=inertia,
+    )
+    return link, False
+
+
+def _xyz_rpy(
+    origin: ET.Element | None,
+) -> tuple[tuple[float, float, float], tuple[float, float, float]]:
+    xyz = tuple(
+        float(x) for x in (origin.get("xyz", "0 0 0") if origin is not None else "0 0 0").split()
+    )
+    rpy = tuple(
+        float(x) for x in (origin.get("rpy", "0 0 0") if origin is not None else "0 0 0").split()
+    )
+    return xyz, rpy  # type: ignore[return-value]
+
+
+def _structure_hash(root: ET.Element) -> str:
+    """Hash of the kinematic topology: sorted joints (name, type, parent, child,
+    origin) + sorted link names. Rounded so float noise doesn't churn the hash."""
+    lines: list[str] = []
+    for joint in root.findall("joint"):
+        parent = joint.find("parent")
+        child = joint.find("child")
+        xyz, rpy = _xyz_rpy(joint.find("origin"))
+        nums = " ".join(f"{v:.6f}" for v in xyz + rpy)
+        lines.append(
+            "|".join(
+                [
+                    joint.get("name", "?"),
+                    joint.get("type", "?"),
+                    parent.get("link", "?") if parent is not None else "?",
+                    child.get("link", "?") if child is not None else "?",
+                    nums,
+                ]
+            )
+        )
+    lines.sort()
+    lines += sorted(link.get("name", "?") for link in root.findall("link"))
+    return hashlib.sha256("\n".join(lines).encode()).hexdigest()
+
+
+def _parse_joint(el: ET.Element) -> Joint:
+    """URDF joint -> schema Joint; consumed by URDF drift."""
+    parent = el.find("parent")
+    child = el.find("child")
+    xyz, rpy = _xyz_rpy(el.find("origin"))
+    axis_el = el.find("axis")
+    axis = None
+    if axis_el is not None:
+        axis = tuple(float(x) for x in axis_el.get("xyz", "0 0 1").split())  # type: ignore[assignment]
+    limit_el = el.find("limit")
+    limits = None
+    if limit_el is not None:
+        lower_raw, upper_raw = limit_el.get("lower"), limit_el.get("upper")
+        effort_raw, velocity_raw = limit_el.get("effort"), limit_el.get("velocity")
+        limits = JointLimits(
+            lower=float(lower_raw) if lower_raw is not None else None,
+            upper=float(upper_raw) if upper_raw is not None else None,
+            effort=float(effort_raw) if effort_raw is not None else None,
+            velocity=float(velocity_raw) if velocity_raw is not None else None,
+        )
+    return Joint(
+        name=el.get("name", "?"),
+        type=el.get("type", "fixed"),  # type: ignore[arg-type]
+        parent=parent.get("link", "?") if parent is not None else "?",
+        child=child.get("link", "?") if child is not None else "?",
+        origin=JointOrigin(xyz=xyz, rpy=rpy),
+        axis=axis,
+        limits=limits,
+    )
+
+
+@dataclass(frozen=True)
+class UrdfTopology:
+    """Link/joint sets extracted for structure-hash drift comparison."""
+
+    link_names: frozenset[str]
+    joints: tuple[Joint, ...]
+    topology_hash: str  # v0.1 URDF kinematic hash (links + joint poses)
+    record_hash: str  # v0.2 hash over Link/Joint records (axis + limits load-bearing)
+
+
+_DOCTYPE_ENTITY_FORBIDDEN = (
+    "URDF DOCTYPE/ENTITY declarations are not permitted (billion-laughs risk)"
+)
+
+
+def _refuse_doctype_entity(raw: bytes, path: Path) -> None:
+    """Refuse a DOCTYPE/ENTITY-bearing URDF before ``ET.fromstring`` ever sees it.
+
+    stdlib ``xml.etree`` does not resolve *external* entities, but an internal
+    entity declared and referenced within the same document still expands —
+    a 336-byte billion-laughs file grows to a multi-megabyte attribute with no
+    error. Refusing on the raw bytes, the same shape ``schema.py`` uses for
+    YAML anchors/aliases, means the parser never has a chance to expand it.
+    """
+    if b"<!DOCTYPE" in raw or b"<!ENTITY" in raw:
+        raise ValueError(f"{path}: {_DOCTYPE_ENTITY_FORBIDDEN}")
+
+
+def read_urdf_topology(path: Path) -> UrdfTopology:
+    """Read on-disk URDF topology for drift checks. Raises on I/O or parse errors."""
+    raw = path.read_bytes()
+    _refuse_doctype_entity(raw, path)
+    root = ET.fromstring(raw)
+    if root.tag != "robot":
+        raise ValueError(f"{path}: root element is <{root.tag}>, expected <robot>")
+    _refuse_unresolved_xacro(root, path)
+    links = [Link(name=el.get("name", "?")) for el in root.findall("link")]
+    joints = tuple(_parse_joint(el) for el in root.findall("joint"))
+    return UrdfTopology(
+        link_names=frozenset(link.name for link in links),
+        joints=joints,
+        topology_hash=_structure_hash(root),
+        record_hash=_model_structure_hash(links, list(joints)),
+    )
+
+
+def describe_structure_drift(model: ModelRecord, topology: UrdfTopology) -> str:
+    """Name added/removed/moved link and joint elements; not merely 'hash differs'."""
+    contract_links = {link.name for link in model.links}
+    parts: list[str] = []
+    added_links = sorted(topology.link_names - contract_links)
+    removed_links = sorted(contract_links - topology.link_names)
+    if added_links:
+        parts.append("link added: " + ", ".join(added_links))
+    if removed_links:
+        parts.append("link removed: " + ", ".join(removed_links))
+
+    # v0.1 init records omit joints[]; only diff joints when the contract locked them.
+    if model.joints:
+        disk_joints = {joint.name: joint for joint in topology.joints}
+        contract_joints = {joint.name: joint for joint in model.joints}
+        added_joints = sorted(disk_joints.keys() - contract_joints.keys())
+        removed_joints = sorted(contract_joints.keys() - disk_joints.keys())
+        if added_joints:
+            parts.append("joint added: " + ", ".join(added_joints))
+        if removed_joints:
+            parts.append("joint removed: " + ", ".join(removed_joints))
+
+        moved: list[str] = []
+        for name in sorted(disk_joints.keys() & contract_joints.keys()):
+            disk = disk_joints[name]
+            locked = contract_joints[name]
+            changes: list[str] = []
+            if (disk.parent, disk.child) != (locked.parent, locked.child):
+                changes.append(
+                    f"parent/child {locked.parent}->{locked.child} -> {disk.parent}->{disk.child}"
+                )
+            if disk.type != locked.type:
+                changes.append(f"type {locked.type} -> {disk.type}")
+            if disk.origin.xyz != locked.origin.xyz or disk.origin.rpy != locked.origin.rpy:
+                changes.append("origin moved")
+            if disk.axis != locked.axis:
+                changes.append("axis changed")
+            if disk.limits != locked.limits:
+                changes.append("limits changed")
+            if changes:
+                moved.append(f"{name} ({'; '.join(changes)})")
+        if moved:
+            parts.append("joint moved: " + ", ".join(moved))
+    elif topology.joints:
+        # Contract predates this fix (or was locked from a joint-less source): the
+        # hash may still be moving on joint changes the link diff above can't see.
+        parts.append("joints not recorded in this contract — re-run init to record them")
+
+    if not parts:
+        parts.append("kinematic topology changed")
+    return "; ".join(parts)
+
+
+def parse_urdf(path: Path) -> ModelRecord:
+    raw = path.read_bytes()
+    _refuse_doctype_entity(raw, path)
+    root = ET.fromstring(raw)
+    if root.tag != "robot":
+        raise ValueError(f"{path}: root element is <{root.tag}>, expected <robot>")
+    _refuse_unresolved_xacro(root, path)
+
+    links: list[Link] = []
+    zero_mass: list[str] = []
+    for el in root.findall("link"):
+        link, is_zero = _parse_link(el)
+        links.append(link)
+        if is_zero:
+            zero_mass.append(link.name)
+
+    joints = [_parse_joint(el) for el in root.findall("joint")]
+
+    return ModelRecord(
+        source=str(path),
+        source_sha256=hashlib.sha256(raw).hexdigest(),
+        # v0.1 hash; overridden by the schema validator once joints (below) are non-empty.
+        structure_hash=_structure_hash(root),
+        links=links,
+        joints=joints,
+        zero_mass_links=sorted(zero_mass),
+        provenance=Provenance(witness="w2", source=str(path), locked_at=dt.date.today()),
+    )