abelien-harness 0.4.0 → 0.6.0

package/skills/abelien-structure/worker/abelien_cad.py

@@ -0,0 +1,585 @@
+"""Small, deterministic Build123d helpers for generated Abelien product CAD."""
+import build123d as bd
+import math
+
+
+LIBRARY_VERSION = "abelien-cad.v1"
+__all__ = [
+    "rounded_rect", "circle_profile", "stadium", "outline",
+    "extrude_profile", "revolve_profile", "shell_body", "lid_for", "split_at",
+    "boss", "holes", "cutout_tool", "cutout", "fillet_edges", "chamfer_edges",
+    "place", "pattern", "mirror_part", "hardware_envelope", "pose", "occurrence",
+    "collision", "containment", "opening", "mark_simplified", "mark_envelope",
+]
+
+
+class CadLibError(ValueError):
+    def __init__(self, code, message):
+        super().__init__(f"abelien_cad.{code}: {message}")
+        self.code = code
+
+
+_UNSET = object()
+_RECORDS = []
+_FACES = ("+X", "-X", "+Y", "-Y", "+Z", "-Z")
+_HARDWARE_KINDS = (
+    "compute-board", "accelerator", "display", "camera", "mic", "speaker", "box",
+    "battery", "button", "coil", "connector",
+)
+
+
+def _fail(code, message):
+    raise CadLibError(code, message)
+
+
+def _record(value):
+    if len(_RECORDS) >= 512:
+        _fail("invalid_argument", "representation records exceed the supported bound")
+    _RECORDS.append(value)
+
+
+def _number(value, name, *, positive=False, nonnegative=False):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        _fail("invalid_argument", f"{name} must be finite")
+    result = float(value)
+    if positive and result <= 0:
+        _fail("invalid_argument", f"{name} must be positive")
+    if nonnegative and result < 0:
+        _fail("invalid_argument", f"{name} must be nonnegative")
+    if abs(result) > 1_000_000:
+        _fail("invalid_argument", f"{name} is outside the supported range")
+    return result
+
+
+def _vector(value, length, name, *, positive=False):
+    if not isinstance(value, (list, tuple)) or len(value) != length:
+        _fail("invalid_argument", f"{name} must contain {length} numbers")
+    return tuple(_number(item, f"{name}[{index}]", positive=positive) for index, item in enumerate(value))
+
+
+def _text(value, name, *, maximum=300):
+    if not isinstance(value, str) or not value.strip() or len(value) > maximum:
+        _fail("invalid_argument", f"{name} must be a non-empty bounded string")
+    return value.strip()
+
+
+def _identifier(value, name, *, stable=False):
+    value = _text(value, name, maximum=128)
+    alphabet = "abcdefghijklmnopqrstuvwxyz0123456789._:-" if stable else "abcdefghijklmnopqrstuvwxyz0123456789_-"
+    if value[0] not in "abcdefghijklmnopqrstuvwxyz0123456789" or any(char not in alphabet for char in value):
+        _fail("invalid_argument", f"{name} has an invalid identifier")
+    return value
+
+
+def _shape(value, name="shape", *, solid=False):
+    if not isinstance(value, bd.Shape) or not value.is_valid:
+        _fail("invalid_argument", f"{name} must be a valid build123d Shape")
+    if solid and (not math.isfinite(float(value.volume)) or float(value.volume) <= 0 or not value.solids()):
+        _fail("geometry_invalid", f"{name} must contain a non-empty solid")
+    return value
+
+
+def _profile(value):
+    value = _shape(value, "profile")
+    box = value.bounding_box()
+    if not math.isfinite(float(value.area)) or float(value.area) <= 0 or abs(float(box.size.Z)) > 1e-7:
+        _fail("profile_invalid", "profile must be a non-empty planar face in XY")
+    return value
+
+
+def _solid(value, message="operation did not make valid solid geometry"):
+    if not isinstance(value, bd.Shape) or not value.is_valid or not value.solids() or not math.isfinite(float(value.volume)) or float(value.volume) <= 0:
+        _fail("geometry_invalid", message)
+    return value
+
+
+def _cut(body, tool):
+    body = _shape(body, "body", solid=True)
+    tool = _shape(tool, "tool", solid=True)
+    before = float(body.volume)
+    try:
+        result = body.cut(tool)
+    except Exception as exc:
+        _fail("cut_no_effect", f"cut failed: {type(exc).__name__}")
+    after = float(result.volume) if isinstance(result, bd.Shape) else before
+    tolerance = max(1e-9, before * 1e-12)
+    if not isinstance(result, bd.Shape) or not result.is_valid or not math.isfinite(after) or before - after <= tolerance:
+        _fail("cut_no_effect", "requested cutter removed no measurable volume")
+    if after <= tolerance or not result.solids():
+        _fail("geometry_invalid", "requested cutter removed the entire body")
+    return result
+
+
+def rounded_rect(*, width, depth, radius):
+    width = _number(width, "width", positive=True)
+    depth = _number(depth, "depth", positive=True)
+    radius = _number(radius, "radius", positive=True)
+    if radius >= min(width, depth) / 2:
+        _fail("geometry_invalid", "radius must be less than half the shorter side")
+    try:
+        return _profile(bd.RectangleRounded(width, depth, radius))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"rounded rectangle failed: {type(exc).__name__}")
+
+
+def circle_profile(*, diameter):
+    diameter = _number(diameter, "diameter", positive=True)
+    try:
+        return _profile(bd.Circle(diameter / 2))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"circle failed: {type(exc).__name__}")
+
+
+def stadium(*, width, depth):
+    width = _number(width, "width", positive=True)
+    depth = _number(depth, "depth", positive=True)
+    try:
+        if abs(width - depth) <= 1e-12:
+            result = bd.Circle(width / 2)
+        elif width > depth:
+            result = bd.SlotOverall(width, depth)
+        else:
+            result = bd.SlotOverall(depth, width, rotation=90)
+        return _profile(result)
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"stadium failed: {type(exc).__name__}")
+
+
+def outline(*, start, path):
+    start = _vector(start, 2, "start")
+    if not isinstance(path, (list, tuple)) or not path or len(path) > 128:
+        _fail("invalid_argument", "path must contain 1..128 segments")
+    current = start
+    edges = []
+    try:
+        for index, segment in enumerate(path):
+            if not isinstance(segment, dict) or len(segment) != 1:
+                _fail("invalid_argument", f"path[{index}] must contain one operation")
+            if "line_to" in segment:
+                end = _vector(segment["line_to"], 2, f"path[{index}].line_to")
+                if math.dist(current, end) <= 1e-9:
+                    _fail("profile_invalid", "line segment is degenerate")
+                edges.append(bd.Line(current, end))
+            elif "arc_to" in segment:
+                arc = segment["arc_to"]
+                if not isinstance(arc, dict) or set(arc) != {"through", "end"}:
+                    _fail("invalid_argument", f"path[{index}].arc_to has invalid keys")
+                through = _vector(arc["through"], 2, f"path[{index}].arc_to.through")
+                end = _vector(arc["end"], 2, f"path[{index}].arc_to.end")
+                edges.append(bd.ThreePointArc(current, through, end))
+            else:
+                _fail("invalid_argument", f"path[{index}] has an unknown operation")
+            current = end
+        if math.dist(current, start) > 1e-9:
+            edges.append(bd.Line(current, start))
+        wire = bd.Wire(edges)
+        if not wire.is_closed:
+            _fail("profile_invalid", "outline did not close")
+        face = bd.Face(wire)
+        if not face.is_valid or not math.isfinite(float(face.area)) or float(face.area) <= 0:
+            _fail("profile_invalid", "outline is invalid or self-intersecting")
+        return face
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("profile_invalid", f"outline failed: {type(exc).__name__}")
+
+
+def extrude_profile(profile, *, height):
+    profile = _profile(profile)
+    height = _number(height, "height", positive=True)
+    try:
+        return _solid(bd.extrude(profile, amount=height))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"extrude failed: {type(exc).__name__}")
+
+
+def revolve_profile(*, points, angle_deg=360):
+    if not isinstance(points, (list, tuple)) or not 3 <= len(points) <= 128:
+        _fail("invalid_argument", "points must contain 3..128 radius/z pairs")
+    angle_deg = _number(angle_deg, "angle_deg", positive=True)
+    if angle_deg > 360:
+        _fail("invalid_argument", "angle_deg must be at most 360")
+    pairs = [_vector(point, 2, f"points[{index}]") for index, point in enumerate(points)]
+    if any(radius < 0 for radius, _ in pairs):
+        _fail("profile_invalid", "radius values must be nonnegative")
+    if math.dist(pairs[0], pairs[-1]) <= 1e-9:
+        pairs = pairs[:-1]
+    if len(pairs) < 3:
+        _fail("profile_invalid", "half profile is degenerate")
+    vertices = [(radius, 0, z) for radius, z in pairs]
+    try:
+        edges = [bd.Line(vertices[index], vertices[(index + 1) % len(vertices)]) for index in range(len(vertices))]
+        wire = bd.Wire(edges)
+        face = bd.Face(wire)
+        if not wire.is_closed or not face.is_valid or float(face.area) <= 0:
+            _fail("profile_invalid", "half profile is invalid or self-intersecting")
+        return _solid(bd.revolve(face, axis=bd.Axis.Z, revolution_arc=angle_deg))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"revolve failed: {type(exc).__name__}")
+
+
+def shell_body(profile, *, height, wall, floor, open_face="top", edge_radius=0):
+    profile = _profile(profile)
+    height = _number(height, "height", positive=True)
+    wall = _number(wall, "wall", positive=True)
+    floor = _number(floor, "floor", positive=True)
+    edge_radius = _number(edge_radius, "edge_radius", nonnegative=True)
+    if open_face not in ("top", "bottom"):
+        _fail("invalid_argument", "open_face must be top or bottom")
+    size = profile.bounding_box().size
+    if 2 * wall >= min(float(size.X), float(size.Y)) or floor >= height:
+        _fail("geometry_invalid", "wall or floor leaves no interior cavity")
+    try:
+        inner = _profile(bd.offset(profile, amount=-wall))
+        outer_solid = extrude_profile(profile, height=height)
+        cavity_height = height - floor + 1e-6
+        cavity = extrude_profile(inner, height=cavity_height)
+        cavity = place(cavity, at=(0, 0, floor if open_face == "top" else -1e-6))
+        result = _cut(outer_solid, cavity)
+        if edge_radius:
+            result = fillet_edges(result, select="top_outer" if open_face == "top" else "bottom_outer", radius=edge_radius)
+        return _solid(result)
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"shell failed: {type(exc).__name__}")
+
+
+def lid_for(profile, *, wall, thickness, lip_height, clearance):
+    profile = _profile(profile)
+    wall = _number(wall, "wall", positive=True)
+    thickness = _number(thickness, "thickness", positive=True)
+    lip_height = _number(lip_height, "lip_height", positive=True)
+    clearance = _number(clearance, "clearance", nonnegative=True)
+    try:
+        lip_outer = _profile(bd.offset(profile, amount=-(wall + clearance)))
+        lip_inner = _profile(bd.offset(lip_outer, amount=-wall))
+        lip = _cut(extrude_profile(lip_outer, height=lip_height), extrude_profile(lip_inner, height=lip_height + 1e-6))
+        plate = place(extrude_profile(profile, height=thickness), at=(0, 0, lip_height))
+        return _solid(lip.fuse(plate))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"lid failed: {type(exc).__name__}")
+
+
+def split_at(shape, *, z):
+    shape = _shape(shape, solid=True)
+    z = _number(z, "z")
+    try:
+        plane = bd.Plane.XY.offset(z)
+        lower = bd.split(shape, bisect_by=plane, keep=bd.Keep.BOTTOM)
+        upper = bd.split(shape, bisect_by=plane, keep=bd.Keep.TOP)
+        if not all(isinstance(item, bd.Shape) and item.is_valid and item.solids() and float(item.volume) > 0 for item in (lower, upper)):
+            _fail("split_empty", "split must leave valid solids on both sides")
+        return lower, upper
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("split_empty", f"split failed: {type(exc).__name__}")
+
+
+def boss(*, outer_diameter, height, hole_diameter, hole_depth):
+    outer_diameter = _number(outer_diameter, "outer_diameter", positive=True)
+    height = _number(height, "height", positive=True)
+    hole_diameter = _number(hole_diameter, "hole_diameter", positive=True)
+    hole_depth = _number(hole_depth, "hole_depth", positive=True)
+    if hole_diameter >= outer_diameter or hole_depth >= height:
+        _fail("geometry_invalid", "pilot hole must be narrower and must not pass through the boss")
+    try:
+        outer = bd.Cylinder(outer_diameter / 2, height, align=(bd.Align.CENTER, bd.Align.CENTER, bd.Align.MIN))
+        cutter = bd.Cylinder(hole_diameter / 2, hole_depth + 1e-6, align=(bd.Align.CENTER, bd.Align.CENTER, bd.Align.MIN))
+        cutter = place(cutter, at=(0, 0, height - hole_depth))
+        return _solid(_cut(outer, cutter))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"boss failed: {type(exc).__name__}")
+
+
+def _face_frame(body, face, center):
+    if face not in _FACES:
+        _fail("invalid_argument", "face must be one of +X, -X, +Y, -Y, +Z, -Z")
+    u, v = _vector(center, 2, "center")
+    box = body.bounding_box()
+    epsilon = 1e-6
+    frames = {
+        "+X": ((float(box.max.X) + epsilon, u, v), (0, -1, 0), (-1, 0, 0)),
+        "-X": ((float(box.min.X) - epsilon, u, v), (0, 1, 0), (1, 0, 0)),
+        "+Y": ((u, float(box.max.Y) + epsilon, v), (1, 0, 0), (0, -1, 0)),
+        "-Y": ((u, float(box.min.Y) - epsilon, v), (-1, 0, 0), (0, 1, 0)),
+        "+Z": ((u, v, float(box.max.Z) + epsilon), (-1, 0, 0), (0, 0, -1)),
+        "-Z": ((u, v, float(box.min.Z) - epsilon), (1, 0, 0), (0, 0, 1)),
+    }
+    return frames[face]
+
+
+def cutout_tool(body, *, face, center, size=None, diameter=None, corner_radius=0, depth):
+    body = _shape(body, "body", solid=True)
+    depth = _number(depth, "depth", positive=True)
+    corner_radius = _number(corner_radius, "corner_radius", nonnegative=True)
+    if (size is None) == (diameter is None):
+        _fail("invalid_argument", "provide exactly one of size or diameter")
+    if diameter is not None:
+        diameter = _number(diameter, "diameter", positive=True)
+        if corner_radius:
+            _fail("invalid_argument", "corner_radius is only valid with size")
+        profile = circle_profile(diameter=diameter)
+    else:
+        width, height = _vector(size, 2, "size", positive=True)
+        if corner_radius >= min(width, height) / 2:
+            _fail("geometry_invalid", "corner_radius must be less than half the shorter cutout side")
+        profile = rounded_rect(width=width, depth=height, radius=corner_radius) if corner_radius else bd.Rectangle(width, height)
+    origin, x_dir, inward = _face_frame(body, face, center)
+    try:
+        plane = bd.Plane(origin=origin, x_dir=x_dir, z_dir=inward)
+        placed_profile = profile.moved(plane.location)
+        return _solid(bd.extrude(placed_profile, amount=depth + 2e-6))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"cutout tool failed: {type(exc).__name__}")
+
+
+def cutout(body, *, face, center, size=None, diameter=None, corner_radius=0, depth):
+    return _cut(body, cutout_tool(body, face=face, center=center, size=size, diameter=diameter,
+                                  corner_radius=corner_radius, depth=depth))
+
+
+def holes(body, *, positions, diameter, depth, from_face="+Z", counterbore=None):
+    body = _shape(body, "body", solid=True)
+    diameter = _number(diameter, "diameter", positive=True)
+    depth = _number(depth, "depth", positive=True)
+    if not isinstance(positions, (list, tuple)) or not positions or len(positions) > 128:
+        _fail("invalid_argument", "positions must contain 1..128 face-local pairs")
+    positions = [_vector(item, 2, f"positions[{index}]") for index, item in enumerate(positions)]
+    if len(set(positions)) != len(positions):
+        _fail("invalid_argument", "positions must be unique")
+    if counterbore is not None:
+        if not isinstance(counterbore, dict) or set(counterbore) != {"diameter", "depth"}:
+            _fail("invalid_argument", "counterbore has invalid keys")
+        counterbore_diameter = _number(counterbore["diameter"], "counterbore.diameter", positive=True)
+        counterbore_depth = _number(counterbore["depth"], "counterbore.depth", positive=True)
+        if counterbore_diameter <= diameter or counterbore_depth >= depth:
+            _fail("geometry_invalid", "counterbore must be wider and shallower than the hole")
+    result = body
+    for position in positions:
+        result = cutout(result, face=from_face, center=position, diameter=diameter, depth=depth)
+        if counterbore is not None:
+            result = cutout(result, face=from_face, center=position, diameter=counterbore_diameter, depth=counterbore_depth)
+    return result
+
+
+def _selected_edges(shape, select):
+    if select not in ("outer_vertical", "top_outer", "bottom_outer"):
+        _fail("invalid_argument", "unknown edge selector")
+    box = shape.bounding_box()
+    span = max(float(box.size.X), float(box.size.Y), float(box.size.Z), 1.0)
+    tolerance = span * 1e-7
+    result = []
+    for edge in shape.edges():
+        bounds = edge.bounding_box()
+        touches_outer = (
+            abs(float(bounds.min.X) - float(box.min.X)) <= tolerance or
+            abs(float(bounds.max.X) - float(box.max.X)) <= tolerance or
+            abs(float(bounds.min.Y) - float(box.min.Y)) <= tolerance or
+            abs(float(bounds.max.Y) - float(box.max.Y)) <= tolerance
+        )
+        vertical = float(bounds.size.Z) > tolerance and float(bounds.size.X) <= tolerance and float(bounds.size.Y) <= tolerance
+        at_top = abs(float(bounds.min.Z) - float(box.max.Z)) <= tolerance and abs(float(bounds.max.Z) - float(box.max.Z)) <= tolerance
+        at_bottom = abs(float(bounds.min.Z) - float(box.min.Z)) <= tolerance and abs(float(bounds.max.Z) - float(box.min.Z)) <= tolerance
+        if touches_outer and ((select == "outer_vertical" and vertical) or (select == "top_outer" and at_top) or (select == "bottom_outer" and at_bottom)):
+            result.append(edge)
+    if not result:
+        _fail("selector_empty", f"{select} selected no edges")
+    return result
+
+
+def _edge_failure(shape, *, operation, select, value, on_fail, part, invoke):
+    shape = _shape(shape, solid=True)
+    value = _number(value, operation, positive=True)
+    if on_fail not in ("raise", "record") or (on_fail == "record" and part is None) or (on_fail == "raise" and part is not None):
+        _fail("invalid_argument", "on_fail=record requires part; raise mode does not accept part")
+    if part is not None:
+        part = _identifier(part, "part")
+    edges = _selected_edges(shape, select)
+    try:
+        return _solid(invoke(edges, value))
+    except Exception as exc:
+        if on_fail == "record":
+            mark_simplified(occurrence_id=part, omitted=[f"{operation}:{select}"],
+                            reason=f"requested {operation} {value:g} mm failed without parameter reduction",
+                            affects=["edge_finish"])
+            return shape
+        _fail("fillet_failed", f"{operation} failed without parameter reduction: {type(exc).__name__}")
+
+
+def fillet_edges(shape, *, select, radius, on_fail="raise", part=None):
+    return _edge_failure(shape, operation="fillet", select=select, value=radius, on_fail=on_fail, part=part,
+                         invoke=lambda edges, value: bd.fillet(edges, value))
+
+
+def chamfer_edges(shape, *, select, length, on_fail="raise", part=None):
+    return _edge_failure(shape, operation="chamfer", select=select, value=length, on_fail=on_fail, part=part,
+                         invoke=lambda edges, value: bd.chamfer(edges, value))
+
+
+def place(shape, *, at=(0, 0, 0), rotate_deg=(0, 0, 0)):
+    shape = _shape(shape)
+    at = _vector(at, 3, "at")
+    rotate_deg = _vector(rotate_deg, 3, "rotate_deg")
+    try:
+        return shape.moved(bd.Location(at, rotate_deg))
+    except Exception as exc:
+        _fail("geometry_invalid", f"placement failed: {type(exc).__name__}")
+
+
+def pattern(shape, *, positions):
+    shape = _shape(shape)
+    if not isinstance(positions, (list, tuple)) or not positions or len(positions) > 128:
+        _fail("invalid_argument", "positions must contain 1..128 translations")
+    positions = [_vector(item, 3, f"positions[{index}]") for index, item in enumerate(positions)]
+    if len(set(positions)) != len(positions):
+        _fail("invalid_argument", "positions must be unique")
+    try:
+        return _shape(bd.Compound(children=[place(shape, at=position) for position in positions]))
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"pattern failed: {type(exc).__name__}")
+
+
+def mirror_part(shape, *, plane):
+    shape = _shape(shape, solid=True)
+    planes = {"XY": bd.Plane.XY, "XZ": bd.Plane.XZ, "YZ": bd.Plane.YZ}
+    if plane not in planes:
+        _fail("invalid_argument", "plane must be XY, XZ or YZ")
+    try:
+        result = _solid(shape.mirror(planes[plane]))
+        if abs(float(result.volume) - float(shape.volume)) > max(1e-7, float(shape.volume) * 1e-9):
+            _fail("geometry_invalid", "mirror changed part volume")
+        return result
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"mirror failed: {type(exc).__name__}")
+
+
+def hardware_envelope(*, kind, size):
+    if kind not in _HARDWARE_KINDS:
+        _fail("invalid_argument", "unknown hardware envelope kind")
+    size = _vector(size, 3, "size", positive=True)
+    try:
+        result = _solid(bd.Box(*size, align=(bd.Align.CENTER, bd.Align.CENTER, bd.Align.MIN)))
+        measured = tuple(float(value) for value in result.bounding_box().size)
+        if any(abs(measured[index] - size[index]) > 1e-6 for index in range(3)):
+            _fail("envelope_mismatch", "measured bounding box differs from native hardware size")
+        return result
+    except CadLibError:
+        raise
+    except Exception as exc:
+        _fail("geometry_invalid", f"hardware envelope failed: {type(exc).__name__}")
+
+
+def pose(*, translation_mm=(0, 0, 0), rotation_deg=(0, 0, 0), visible=True):
+    if not isinstance(visible, bool):
+        _fail("invalid_argument", "visible must be boolean")
+    return {"translation_mm": list(_vector(translation_mm, 3, "translation_mm")),
+            "rotation_deg": list(_vector(rotation_deg, 3, "rotation_deg")), "visible": visible}
+
+
+def occurrence(*, occurrence_id, component_id, bom_item_id, label, shape, geometry_precision,
+               normal, internal, exploded, mount_frames=_UNSET, interfaces=_UNSET,
+               appearance_bindings=_UNSET, lineage=_UNSET, material=_UNSET):
+    result = {
+        "occurrence_id": _identifier(occurrence_id, "occurrence_id"),
+        "component_id": _identifier(component_id, "component_id", stable=True),
+        "bom_item_id": _identifier(bom_item_id, "bom_item_id", stable=True),
+        "label": _text(label, "label", maximum=100),
+        "shape": _shape(shape, solid=True),
+        "geometry_precision": geometry_precision,
+        "normal": normal, "internal": internal, "exploded": exploded,
+    }
+    if geometry_precision not in ("custom_brep", "envelope"):
+        _fail("invalid_argument", "geometry_precision must be custom_brep or envelope")
+    for name, value in (("normal", normal), ("internal", internal), ("exploded", exploded)):
+        if not isinstance(value, dict) or set(value) != {"translation_mm", "rotation_deg", "visible"}:
+            _fail("invalid_argument", f"{name} must be a pose")
+        pose(translation_mm=value["translation_mm"], rotation_deg=value["rotation_deg"], visible=value["visible"])
+    for name, value in (("mount_frames", mount_frames), ("interfaces", interfaces), ("appearance_bindings", appearance_bindings)):
+        if value is not _UNSET and not isinstance(value, list):
+            _fail("invalid_argument", f"{name} must be a list")
+    if lineage is not _UNSET and lineage is not None and not isinstance(lineage, dict):
+        _fail("invalid_argument", "lineage must be an object or None")
+    if material is not _UNSET and not isinstance(material, dict):
+        _fail("invalid_argument", "material must be an object")
+    for name, value in (("mount_frames", mount_frames), ("interfaces", interfaces),
+                        ("appearance_bindings", appearance_bindings), ("lineage", lineage), ("material", material)):
+        if value is not _UNSET:
+            result[name] = value
+    return result
+
+
+def collision(*, occurrence_ids, allowed_pairs=(), maximum_overlap_mm3=0):
+    if not isinstance(occurrence_ids, (list, tuple)) or not 2 <= len(occurrence_ids) <= 128:
+        _fail("invalid_argument", "occurrence_ids must contain 2..128 identities")
+    ids = [_identifier(item, "occurrence_ids[]") for item in occurrence_ids]
+    if len(set(ids)) != len(ids) or not isinstance(allowed_pairs, (list, tuple)) or len(allowed_pairs) > 8128:
+        _fail("invalid_argument", "collision identities or allowed_pairs are invalid")
+    pairs = []
+    for index, pair in enumerate(allowed_pairs):
+        if not isinstance(pair, (list, tuple)) or len(pair) != 2 or pair[0] == pair[1] or any(item not in ids for item in pair):
+            _fail("invalid_argument", f"allowed_pairs[{index}] is invalid")
+        normalized = sorted(pair)
+        if normalized in pairs:
+            _fail("invalid_argument", "allowed_pairs contains a duplicate")
+        pairs.append(normalized)
+    return {"occurrence_ids": ids, "allowed_pairs": pairs,
+            "maximum_overlap_mm3": _number(maximum_overlap_mm3, "maximum_overlap_mm3", nonnegative=True)}
+
+
+def containment(*, container, targets, maximum_outside_mm3=0):
+    container = _identifier(container, "container")
+    if not isinstance(targets, (list, tuple)) or not targets or len(targets) > 128:
+        _fail("invalid_argument", "targets must contain 1..128 identities")
+    targets = [_identifier(item, "targets[]") for item in targets]
+    if container in targets or len(set(targets)) != len(targets):
+        _fail("invalid_argument", "containment identities are invalid")
+    return {"container": container, "targets": targets,
+            "maximum_outside_mm3": _number(maximum_outside_mm3, "maximum_outside_mm3", nonnegative=True)}
+
+
+def opening(*, opening, target, maximum_distance_mm, minimum_overlap_mm3):
+    opening_id = _identifier(opening, "opening")
+    target = _identifier(target, "target")
+    if opening_id == target:
+        _fail("invalid_argument", "opening and target must differ")
+    return {"opening": opening_id, "target": target,
+            "maximum_distance_mm": _number(maximum_distance_mm, "maximum_distance_mm", nonnegative=True),
+            "minimum_overlap_mm3": _number(minimum_overlap_mm3, "minimum_overlap_mm3", nonnegative=True)}
+
+
+def mark_simplified(*, occurrence_id, omitted, reason, affects):
+    occurrence_id = _identifier(occurrence_id, "occurrence_id")
+    if not isinstance(omitted, (list, tuple)) or not omitted or len(omitted) > 128 or not isinstance(affects, (list, tuple)) or not affects or len(affects) > 32:
+        _fail("invalid_argument", "omitted and affects must be non-empty bounded lists")
+    omitted = [_text(item, "omitted[]", maximum=200) for item in omitted]
+    affects = [_text(item, "affects[]", maximum=100) for item in affects]
+    _record({"kind": "simplified", "occurrence_id": occurrence_id, "omitted": omitted,
+             "reason": _text(reason, "reason"), "affects": affects})
+
+
+def mark_envelope(*, occurrence_id, reason):
+    _record({"kind": "envelope", "occurrence_id": _identifier(occurrence_id, "occurrence_id"),
+             "reason": _text(reason, "reason")})