gitcad-core 0.7.7__py3-none-any.whl

gitcad/part/assembly.py

@@ -0,0 +1,229 @@
+"""Assemblies — parts whose body is composition (ADR-0008).
+
+An assembly places **instances** of parts by explicit rigid transform and
+declares **mates** between ports. v1 has deliberately no constraint solver:
+mates are *checks* — port-type compatibility and positional coincidence after
+transforms — so assembly validation is interface checking, cheap and exact.
+
+The assembly is itself a Part: :meth:`Assembly.to_manifest` derives its own
+manifest (envelope = union of instance envelopes), which is what makes
+assemblies nest with no special cases.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+from gitcad.errors import GitcadError, ValidationReport
+from gitcad.part.interface import Interface
+from gitcad.part.manifest import PartManifest
+
+# Port types that may mate with each other (symmetric; extended by domains).
+COMPATIBLE_TYPES: set[frozenset[str]] = {
+    frozenset({"mech.bolt", "mech.boss"}),
+    frozenset({"mech.bolt", "mech.bolt"}),
+    frozenset({"elec.connector", "elec.connector"}),
+    frozenset({"elec.pin", "elec.pin"}),
+}
+
+_TOL = 0.01  # mm — positional coincidence tolerance for mates
+
+
+@dataclass
+class Instance:
+    name: str
+    part: PartManifest
+    translate: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    rotate_z_deg: float = 0.0    # v1: rotation about global Z only
+
+    def port_position(self, port_name: str) -> tuple[float, float, float]:
+        iface = self.part.interface
+        if port_name not in iface.ports:
+            raise GitcadError(f"instance {self.name!r}: no port {port_name!r}")
+        frame = iface.frames[iface.ports[port_name].frame]
+        x, y, z = frame.origin
+        rad = math.radians(self.rotate_z_deg)
+        rx = x * math.cos(rad) - y * math.sin(rad)
+        ry = x * math.sin(rad) + y * math.cos(rad)
+        tx, ty, tz = self.translate
+        return (rx + tx, ry + ty, z + tz)
+
+    def envelope_bounds(self) -> tuple[tuple[float, float, float], tuple[float, float, float]] | None:
+        env = self.part.interface.envelope
+        if env is None:
+            return None
+        ox, oy, oz = env.get("origin", (0.0, 0.0, 0.0))
+        dx, dy, dz = env["dx"], env["dy"], env["dz"]
+        corners = [(ox + a, oy + b) for a in (0, dx) for b in (0, dy)]
+        rad = math.radians(self.rotate_z_deg)
+        rot = [(x * math.cos(rad) - y * math.sin(rad), x * math.sin(rad) + y * math.cos(rad))
+               for x, y in corners]
+        tx, ty, tz = self.translate
+        xs = [x + tx for x, _ in rot]
+        ys = [y + ty for _, y in rot]
+        return ((min(xs), min(ys), oz + tz), (max(xs), max(ys), oz + dz + tz))
+
+
+@dataclass
+class Mate:
+    """A declared connection: instance_a.port_a mates instance_b.port_b."""
+    a: str          # "instance.port"
+    b: str
+
+    def split(self) -> tuple[tuple[str, str], tuple[str, str]]:
+        def parse(ref: str) -> tuple[str, str]:
+            if "." not in ref:
+                raise GitcadError(f"mate ref {ref!r} must be 'instance.port'")
+            inst, port = ref.split(".", 1)
+            return inst, port
+        return parse(self.a), parse(self.b)
+
+
+@dataclass
+class Assembly:
+    name: str
+    instances: dict[str, Instance] = field(default_factory=dict)
+    mates: list[Mate] = field(default_factory=list)
+
+    def add(self, name: str, part: PartManifest, *, translate=(0.0, 0.0, 0.0),
+            rotate_z_deg: float = 0.0) -> Instance:
+        if name in self.instances:
+            raise GitcadError(f"duplicate instance name {name!r}")
+        inst = Instance(name, part, tuple(translate), rotate_z_deg)
+        self.instances[name] = inst
+        return inst
+
+    def mate(self, a: str, b: str) -> None:
+        self.mates.append(Mate(a, b))
+
+    # -- component patterns (SW "linear/circular component pattern") -----------
+
+    def pattern_linear(self, seed: str, *, direction, spacing: float,
+                       count: int) -> list[Instance]:
+        """Replicate an existing instance ``count`` times along ``direction``
+        at ``spacing`` apart (count includes the seed). The seed keeps its
+        place; copies are named ``{seed}#1``, ``{seed}#2``, …. Returns the
+        newly created instances (excluding the seed)."""
+        if seed not in self.instances:
+            raise GitcadError(f"pattern_linear: no seed instance {seed!r}")
+        if count < 1:
+            raise GitcadError("pattern_linear: count must be >= 1")
+        base = self.instances[seed]
+        dx, dy, dz = (float(direction[0]), float(direction[1]),
+                      float(direction[2]) if len(direction) > 2 else 0.0)
+        length = math.sqrt(dx * dx + dy * dy + dz * dz)
+        if length < _TOL:
+            raise GitcadError("pattern_linear: zero-length direction")
+        ux, uy, uz = dx / length, dy / length, dz / length
+        made: list[Instance] = []
+        tx, ty, tz = base.translate
+        for k in range(1, count):
+            step = k * spacing
+            name = f"{seed}#{k}"
+            if name in self.instances:
+                raise GitcadError(f"pattern_linear: duplicate copy name {name!r}")
+            inst = Instance(name, base.part,
+                            (tx + ux * step, ty + uy * step, tz + uz * step),
+                            base.rotate_z_deg)
+            self.instances[name] = inst
+            made.append(inst)
+        return made
+
+    def pattern_circular(self, seed: str, *, center=(0.0, 0.0),
+                         count: int, total_angle_deg: float = 360.0) -> list[Instance]:
+        """Replicate an instance ``count`` times about the global Z axis
+        through ``center`` (an XY point). Copies span ``total_angle_deg`` —
+        a full 360° drops the redundant final copy (it would coincide with
+        the seed); a partial arc keeps both ends. Each copy is the seed
+        rigidly rotated about ``center`` (translate revolves, ``rotate_z_deg``
+        advances), which is exact within the rotate-about-Z placement model."""
+        if seed not in self.instances:
+            raise GitcadError(f"pattern_circular: no seed instance {seed!r}")
+        if count < 1:
+            raise GitcadError("pattern_circular: count must be >= 1")
+        base = self.instances[seed]
+        cx, cy = float(center[0]), float(center[1])
+        # a closed 360° ring divides the full turn into ``count`` gaps; an
+        # open arc puts the last copy AT total_angle (count-1 gaps).
+        full = abs((total_angle_deg % 360.0)) < 1e-9 and total_angle_deg != 0.0
+        gaps = count if full else max(count - 1, 1)
+        step_deg = total_angle_deg / gaps
+        tx, ty, tz = base.translate
+        rx, ry = tx - cx, ty - cy
+        made: list[Instance] = []
+        for k in range(1, count):
+            ang = math.radians(step_deg * k)
+            ca, sa = math.cos(ang), math.sin(ang)
+            nx = cx + rx * ca - ry * sa
+            ny = cy + rx * sa + ry * ca
+            name = f"{seed}#{k}"
+            if name in self.instances:
+                raise GitcadError(f"pattern_circular: duplicate copy name {name!r}")
+            inst = Instance(name, base.part, (nx, ny, tz),
+                            base.rotate_z_deg + step_deg * k)
+            self.instances[name] = inst
+            made.append(inst)
+        return made
+
+    # -- validation: interface checking (the whole point) ---------------------
+
+    def validate(self) -> ValidationReport:
+        violations: list[str] = []
+        for m in self.mates:
+            (ia, pa), (ib, pb) = m.split()
+            # Per-mate validity — earlier mates' failures must never swallow
+            # this mate's checks (reviewed 2026-07-22).
+            missing = [i for i in (ia, ib) if i not in self.instances]
+            if missing:
+                violations.extend(f"mate-unknown-instance:{i}" for i in missing)
+                continue
+            inst_a, inst_b = self.instances[ia], self.instances[ib]
+            try:
+                port_a = inst_a.part.interface.ports[pa]
+                port_b = inst_b.part.interface.ports[pb]
+            except KeyError as exc:
+                violations.append(f"mate-unknown-port:{exc.args[0]}")
+                continue
+            if frozenset({port_a.type, port_b.type}) not in COMPATIBLE_TYPES:
+                violations.append(f"mate-incompatible-types:{m.a}({port_a.type})<->{m.b}({port_b.type})")
+            pos_a, pos_b = inst_a.port_position(pa), inst_b.port_position(pb)
+            dist = math.dist(pos_a, pos_b)   # full 3D coincidence
+            if dist > _TOL:
+                violations.append(f"mate-position-mismatch:{m.a}<->{m.b}:d={dist:.3f}mm")
+        # checks states METHOD and coverage so ok=True can never overstate what
+        # was verified (frame orientation is not yet checked, only position).
+        return ValidationReport(
+            ok=not violations,
+            checks={"instances": len(self.instances), "mates": len(self.mates),
+                    "coincidence": "xyz-position", "orientation_checked": False},
+            violations=violations,
+        )
+
+    # -- an assembly is a part ------------------------------------------------
+
+    def to_manifest(self, part_id: str, version: str = "0.1.0") -> PartManifest:
+        """Derive this assembly's own part manifest: union envelope, body =
+        composition, deps = constraints on every instanced part."""
+        bounds = [b for inst in self.instances.values() if (b := inst.envelope_bounds())]
+        envelope = None
+        if bounds:
+            los, his = [b[0] for b in bounds], [b[1] for b in bounds]
+            lo = tuple(min(p[i] for p in los) for i in range(3))
+            hi = tuple(max(p[i] for p in his) for i in range(3))
+            envelope = {"origin": list(lo), "dx": hi[0] - lo[0],
+                        "dy": hi[1] - lo[1], "dz": hi[2] - lo[2]}
+        body = {
+            "kind": "assembly",
+            "instances": {
+                n: {"part": i.part.id, "translate": list(i.translate),
+                    "rotate_z_deg": i.rotate_z_deg}
+                for n, i in sorted(self.instances.items())
+            },
+            "mates": [{"a": m.a, "b": m.b} for m in self.mates],
+        }
+        deps = {i.part.id: f"^{i.part.version}" for i in self.instances.values()}
+        return PartManifest(
+            id=part_id, name=self.name, domain="assembly", version=version,
+            interface=Interface(envelope=envelope), deps=deps, body=body,
+        )

gitcad/part/bought.py

@@ -0,0 +1,62 @@
+"""Bought (COTS) parts — the MPN-atomic pattern, domain-neutral.
+
+The made-vs-bought axis, not mech-vs-ecad, is what determines identity:
+- MADE parts (housing, board): the model is source; identity = name@release.
+- BOUGHT parts (screws, standoffs, cells, pumps, ECAD components): identity
+  = a concrete manufacturer part number, with catalog/datasheet hash anchors
+  and facts-as-properties. Never a parametric generic (antipattern: unties
+  the design from what is actually procured).
+
+:func:`bought_part` builds one for any domain; :func:`assembly_bom` rolls an
+assembly into procurement lines: bought by MPN, made by name@version.
+"""
+
+from __future__ import annotations
+
+import re
+
+from gitcad.errors import GitcadError
+from gitcad.part.assembly import Assembly
+from gitcad.part.interface import Interface
+from gitcad.part.manifest import PartManifest
+
+
+def bought_part(mpn: str, manufacturer: str, part_id: str, *, domain: str = "mech",
+                version: str = "0.1.0", interface: Interface | None = None,
+                params: dict | None = None, datasheet: dict | None = None) -> PartManifest:
+    if datasheet is not None:
+        if "url" not in datasheet or not re.fullmatch(r"[0-9a-f]{64}", datasheet.get("sha256", "")):
+            raise GitcadError("datasheet must be {url, sha256[, retrieved]} (sha256 = 64 hex)")
+    iface = interface or Interface()
+    iface.properties = {"mpn": mpn, "manufacturer": manufacturer, **(params or {})}
+    return PartManifest(
+        id=part_id, name=mpn, domain=domain, version=version, interface=iface,
+        body={"kind": "mpn-part", "mpn": mpn, "manufacturer": manufacturer,
+              **({"datasheet": datasheet} if datasheet else {})},
+    )
+
+
+def is_bought(manifest: PartManifest) -> bool:
+    return (manifest.body or {}).get("kind", "").startswith("mpn-")
+
+
+def assembly_bom(assembly: Assembly) -> list[dict]:
+    """Procurement lines for an assembly: bought parts grouped by MPN, made
+    parts listed by name@version (their identity is the release)."""
+    lines: dict[str, dict] = {}
+    for name, inst in sorted(assembly.instances.items()):
+        m = inst.part
+        if is_bought(m):
+            key = f"mpn:{m.body['mpn']}"
+            line = lines.setdefault(key, {
+                "type": "bought", "mpn": m.body["mpn"],
+                "manufacturer": m.body.get("manufacturer", ""),
+                "instances": [], "qty": 0})
+        else:
+            key = f"made:{m.id}@{m.version}"
+            line = lines.setdefault(key, {
+                "type": "made", "name": m.name, "version": m.version,
+                "part_id": m.id, "instances": [], "qty": 0})
+        line["instances"].append(name)
+        line["qty"] += 1
+    return sorted(lines.values(), key=lambda x: (x["type"], x.get("mpn", x.get("name", ""))))

gitcad/part/exploded.py

@@ -0,0 +1,106 @@
+"""Exploded views — a display projection, never a model edit (ADR-0014).
+
+The spec is per-instance offset vectors in canonical text. Applying it
+produces a *new* assembly with shifted transforms for renderers to consume;
+the source assembly text never changes. ``auto_explode`` derives default
+offsets deterministically from the mate graph: each instance moves along its
+mated port frame's z axis, scaled by its BFS depth from the base instance
+(the most-mated one, ties by name) — no solver, pure derivation.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+
+from gitcad.canonical import canonical_json
+from gitcad.errors import GitcadError
+from gitcad.part.assembly import Assembly
+
+
+@dataclass
+class ExplodedView:
+    assembly: str
+    offsets: dict[str, tuple[float, float, float]] = field(default_factory=dict)
+
+    SCHEMA = "gitcad/exploded-view@1"
+
+    def dumps(self) -> str:
+        doc = {"schema": self.SCHEMA, "exploded": {
+            "assembly": self.assembly,
+            "offsets": {k: list(v) for k, v in sorted(self.offsets.items())}}}
+        return canonical_json(doc, indent=2) + "\n"
+
+    @classmethod
+    def loads(cls, text: str) -> "ExplodedView":
+        doc = json.loads(text)
+        if doc.get("schema") != cls.SCHEMA:
+            raise GitcadError(f"unsupported exploded-view schema {doc.get('schema')!r}")
+        e = doc["exploded"]
+        return cls(assembly=e["assembly"],
+                   offsets={k: tuple(v) for k, v in e.get("offsets", {}).items()})
+
+    def apply(self, asm: Assembly) -> Assembly:
+        """A new assembly with offsets added to instance transforms. Unknown
+        instance names in the spec are an error — a stale view must fail loud,
+        not silently explode the wrong parts."""
+        unknown = set(self.offsets) - set(asm.instances)
+        if unknown:
+            raise GitcadError(f"exploded view names unknown instances: {sorted(unknown)}")
+        out = Assembly(f"{asm.name}-exploded")
+        for name, inst in asm.instances.items():
+            off = self.offsets.get(name, (0.0, 0.0, 0.0))
+            out.add(name, inst.part,
+                    translate=(inst.translate[0] + off[0],
+                               inst.translate[1] + off[1],
+                               inst.translate[2] + off[2]),
+                    rotate_z_deg=inst.rotate_z_deg)
+        out.mates = list(asm.mates)   # carried for reference, not re-checked
+        return out
+
+
+def auto_explode(asm: Assembly, spacing: float = 30.0) -> ExplodedView:
+    """Deterministic default explode derived from the mate graph."""
+    # Adjacency + per-instance mated-port direction.
+    adj: dict[str, set[str]] = {n: set() for n in asm.instances}
+    port_dir: dict[str, tuple[float, float, float]] = {}
+    for mate in asm.mates:
+        (ia, pa), (ib, pb) = mate.split()
+        adj[ia].add(ib)
+        adj[ib].add(ia)
+        for iname, pname in ((ia, pa), (ib, pb)):
+            if iname in port_dir:
+                continue
+            iface = asm.instances[iname].part.interface
+            port = iface.ports.get(pname)
+            if port is not None:
+                port_dir[iname] = tuple(iface.frames[port.frame].z_axis)
+
+    if not asm.instances:
+        return ExplodedView(assembly=asm.name)
+    base = max(adj, key=lambda n: (len(adj[n]), n))
+
+    # BFS depth from base; unmated instances stack above the deepest level.
+    depth = {base: 0}
+    queue = [base]
+    while queue:
+        cur = queue.pop(0)
+        for nxt in sorted(adj[cur]):
+            if nxt not in depth:
+                depth[nxt] = depth[cur] + 1
+                queue.append(nxt)
+    deepest = max(depth.values(), default=0)
+    for i, name in enumerate(sorted(set(asm.instances) - set(depth))):
+        depth[name] = deepest + 1 + i
+
+    offsets: dict[str, tuple[float, float, float]] = {}
+    for name, d in depth.items():
+        if d == 0:
+            continue
+        dx, dy, dz = port_dir.get(name, (0.0, 0.0, 1.0))
+        norm = math.sqrt(dx * dx + dy * dy + dz * dz) or 1.0
+        offsets[name] = (round(dx / norm * spacing * d, 9),
+                         round(dy / norm * spacing * d, 9),
+                         round(dz / norm * spacing * d, 9))
+    return ExplodedView(assembly=asm.name, offsets=offsets)

gitcad/part/interface.py

@@ -0,0 +1,182 @@
+"""The domain-neutral part interface, and the interface-semver enforcer.
+
+The interface is what assemblies and other parts may depend on: envelope,
+named frames, typed ports, informational properties (ADR-0008).
+
+:func:`classify_change` computes the *required* semver bump between two
+interfaces — the machine check that makes "patch releases cannot break you" a
+guarantee instead of a convention (ADR-0009). :func:`check_release` is the CI
+gate built on it.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+
+from gitcad.errors import GitcadError
+from gitcad.part.semver import BUMPS, Version
+
+_TOL = 1e-6  # positional tolerance (mm) below which a move is float noise
+
+
+@dataclass(frozen=True)
+class Frame:
+    """A named coordinate frame: origin + z axis + x axis (y derived)."""
+    origin: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    z_axis: tuple[float, float, float] = (0.0, 0.0, 1.0)
+    x_axis: tuple[float, float, float] = (1.0, 0.0, 0.0)
+
+
+@dataclass(frozen=True)
+class Port:
+    """A typed connection point bound to a frame.
+
+    ``type`` uses an open, namespaced vocabulary: ``mech.bolt``,
+    ``elec.pin``, ``elec.connector``, ... Core standardizes the structure;
+    domains extend the vocabulary (ADR-0008).
+    """
+    name: str
+    type: str
+    frame: str                      # name of a Frame in the same interface
+    spec: dict = field(default_factory=dict)
+
+
+@dataclass
+class Interface:
+    """The domain-neutral projection of a part."""
+    envelope: dict | None = None    # {"origin":[x,y,z], "dx":..,"dy":..,"dz":..}
+    frames: dict[str, Frame] = field(default_factory=dict)
+    ports: dict[str, Port] = field(default_factory=dict)
+    properties: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name, port in self.ports.items():
+            if port.name != name:
+                raise GitcadError(f"port key {name!r} != port.name {port.name!r}")
+            if port.frame not in self.frames:
+                raise GitcadError(f"port {name!r} references unknown frame {port.frame!r}")
+
+    def to_dict(self) -> dict:
+        return {
+            "envelope": self.envelope,
+            "frames": {k: asdict(v) for k, v in sorted(self.frames.items())},
+            "ports": {k: asdict(v) for k, v in sorted(self.ports.items())},
+            "properties": self.properties,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Interface":
+        return cls(
+            envelope=d.get("envelope"),
+            frames={k: Frame(tuple(v["origin"]), tuple(v["z_axis"]), tuple(v["x_axis"]))
+                    for k, v in d.get("frames", {}).items()},
+            ports={k: Port(v["name"], v["type"], v["frame"], dict(v.get("spec", {})))
+                   for k, v in d.get("ports", {}).items()},
+            properties=dict(d.get("properties", {})),
+        )
+
+    def canonical(self) -> str:
+        from gitcad.canonical import canonical_json
+
+        return canonical_json(self.to_dict())
+
+
+# -- the semver enforcer ------------------------------------------------------
+
+def _moved(a: Frame, b: Frame) -> bool:
+    def far(p, q) -> bool:
+        return any(abs(x - y) > _TOL for x, y in zip(p, q))
+    return far(a.origin, b.origin) or far(a.z_axis, b.z_axis) or far(a.x_axis, b.x_axis)
+
+
+def classify_change(old: Interface, new: Interface) -> tuple[str, list[str]]:
+    """Required bump ('major'|'minor'|'patch') + human-readable reasons.
+
+    Rules (ADR-0009): removed/moved frame, removed/retyped/re-specced port, or
+    envelope growth → MAJOR. Added frame/port or envelope shrink → MINOR.
+    Interface identical (properties may differ) → PATCH.
+    """
+    reasons: list[str] = []
+    level = 0  # index into BUMPS
+
+    def require(bump: str, reason: str) -> None:
+        nonlocal level
+        reasons.append(f"{bump.upper()}: {reason}")
+        level = max(level, BUMPS.index(bump))
+
+    for name in old.frames:
+        if name not in new.frames:
+            require("major", f"frame removed: {name}")
+        elif _moved(old.frames[name], new.frames[name]):
+            require("major", f"frame moved: {name}")
+    for name in new.frames:
+        if name not in old.frames:
+            require("minor", f"frame added: {name}")
+
+    for name, port in old.ports.items():
+        if name not in new.ports:
+            require("major", f"port removed: {name}")
+            continue
+        np = new.ports[name]
+        if np.type != port.type:
+            require("major", f"port type changed: {name} ({port.type} -> {np.type})")
+        if np.spec != port.spec:
+            require("major", f"port spec changed: {name}")
+        if np.frame != port.frame:
+            require("major", f"port re-anchored: {name} ({port.frame} -> {np.frame})")
+    for name in new.ports:
+        if name not in old.ports:
+            require("minor", f"port added: {name}")
+
+    if old.envelope != new.envelope:
+        if old.envelope is None:
+            require("minor", "envelope added")
+        elif new.envelope is None:
+            require("major", "envelope removed")
+        else:
+            # Containment semantics (ADR-0009, corrected per 2026-07-22 review):
+            # new fits inside old (within tolerance) -> compatible shrink =
+            # MINOR; identical within tolerance -> no interface change; any
+            # extension beyond the old box -> MAJOR. A centered shrink that
+            # moves the origin is still MINOR — what matters is fit, not the
+            # min corner.
+            def corners(env: dict) -> tuple[tuple[float, ...], tuple[float, ...]]:
+                o = tuple(env.get("origin", (0, 0, 0)))
+                return o, tuple(o[i] + env[k] for i, k in enumerate(("dx", "dy", "dz")))
+
+            (old_lo, old_hi), (new_lo, new_hi) = corners(old.envelope), corners(new.envelope)
+            outside = any(new_lo[i] < old_lo[i] - _TOL or new_hi[i] > old_hi[i] + _TOL
+                          for i in range(3))
+            identical = all(abs(new_lo[i] - old_lo[i]) <= _TOL and
+                            abs(new_hi[i] - old_hi[i]) <= _TOL for i in range(3))
+            if outside:
+                require("major", "envelope extends beyond previous bounds")
+            elif not identical:
+                require("minor", "envelope shrank (fits within previous bounds)")
+            # else: sub-tolerance float noise — not an interface change
+
+    if not reasons:
+        reasons.append("PATCH: interface identical")
+    return BUMPS[level], reasons
+
+
+def check_release(old_version: str, new_version: str,
+                  old_iface: Interface, new_iface: Interface) -> list[str]:
+    """The CI release gate. Returns violations (empty = release is sound).
+
+    Rejects a version bump smaller than the interface change requires — the
+    check that stops an agent (or human) shipping a copper move as a patch.
+    """
+    ov, nv = Version.parse(old_version), Version.parse(new_version)
+    required, reasons = classify_change(old_iface, new_iface)
+    actual = nv.actual_bump_from(ov)
+    violations: list[str] = []
+    if actual is None:
+        violations.append(f"version must increase: {ov} -> {nv}")
+    elif BUMPS.index(actual) < BUMPS.index(required):
+        violations.append(
+            f"insufficient bump: {ov} -> {nv} is {actual.upper()}, interface requires "
+            f"{required.upper()} ({'; '.join(r for r in reasons if r.startswith(required.upper()))})"
+        )
+    return violations

gitcad/part/interference.py

@@ -0,0 +1,71 @@
+"""Real interference checking — co-design upgraded from "probably fits" to
+"provably fits" (list item 4).
+
+Envelope AABBs (Assembly.validate) are the fast pre-filter; this module is
+the exact check: place each instance's real geometry with its transform and
+boolean-intersect every pair. A nonzero common volume is a collision, with
+the overlap measured in mm³ — not a guess, a measurement. Face-on-face
+contact (mated parts touching) intersects with zero volume and passes.
+"""
+
+from __future__ import annotations
+
+from gitcad.errors import ValidationReport
+from gitcad.seams import Kernel, Shape
+
+_VOL_TOL = 1e-6  # mm^3 — below this, "intersection" is contact/noise
+
+
+def check_interference(
+    kernel: Kernel,
+    instances: dict[str, tuple[Shape, tuple[float, float, float], float]],
+    *,
+    ignore: set[frozenset[str]] | None = None,
+    tol_mm3: float | None = None,
+) -> ValidationReport:
+    """``instances``: name -> (shape, translate, rotate_z_deg). ``ignore``:
+    pairs (as frozensets of names) intentionally in contact/overlap.
+    ``tol_mm3``: allowed overlap volume per pair (None = exact, the strict
+    default; a clash budget like 1.0 matches common enclosure practice).
+    The pairwise overlap matrix is always reported — a passing check still
+    shows HOW CLOSE it passed."""
+    ignore = ignore or set()
+    tol = _VOL_TOL if tol_mm3 is None else tol_mm3
+
+    placed: dict[str, Shape] = {}
+    boxes: dict[str, tuple] = {}
+    for name, (shape, translate, rot_z) in instances.items():
+        s = kernel.transform(shape, translate=translate,
+                             rotate_axis=(0, 0, 1), rotate_deg=rot_z)
+        placed[name] = s
+        boxes[name] = kernel.bbox(s)
+
+    def aabb_overlaps(a, b) -> bool:
+        (alo, ahi), (blo, bhi) = a, b
+        return all(alo[i] <= bhi[i] and blo[i] <= ahi[i] for i in range(3))
+
+    violations: list[str] = []
+    overlaps: dict[str, float] = {}
+    names = sorted(placed)
+    checked = 0
+    for i, na in enumerate(names):
+        for nb in names[i + 1:]:
+            if frozenset({na, nb}) in ignore:
+                continue
+            if not aabb_overlaps(boxes[na], boxes[nb]):
+                continue   # envelope pre-filter: cannot collide
+            checked += 1
+            common = kernel.boolean("intersect", placed[na], placed[nb])
+            vol = kernel.measure(common).get("volume", 0.0)
+            if vol > _VOL_TOL:
+                overlaps[f"{na}<->{nb}"] = round(vol, 4)
+            if vol > tol:
+                violations.append(f"interference:{na}<->{nb}:overlap={vol:.3f}mm3")
+
+    return ValidationReport(
+        ok=not violations,
+        checks={"instances": len(instances), "pairs_intersected": checked,
+                "overlaps_mm3": overlaps, "tol_mm3": tol,
+                "method": "exact-boolean-common", "kernel": kernel.name},
+        violations=violations,
+    )