feat(cad): adacpp backend builds natively; keep pythonocc/adacpp independent

Make the adacpp CAD backend stand on its own — no pythonocc fallback (it
also targets wasm, where pythonocc doesn't exist). Two parts:

1. Correct the backend boundary. Phases 3 & 5 routed several ada.occ
   *internal* helpers (transform_shape/_to_pos, rotate_shp_3_axis,
   apply_booleans, apply_geom_booleans, get_points_from_occ_shape,
   get_face_normal, iter_faces_with_normal, serialize_shape, the STEP-writer
   validity check) through active_backend(). Those run on raw pythonocc
   TopoDS shapes mid-construction — a no-op under OccBackend but broken under
   adacpp. Reverted them to pythonocc-direct: they are OccBackend's private
   implementation. The backend *verbs* stay and are used only on final
   handles (cache build, bbox, clash distance) and the tessellation seam.

2. AdacppBackend.build() now dispatches ada.geom natively:
   Box/Cylinder/Sphere/Cone → adacpp.cad.build_* (+ booleans via
   adacpp.cad.boolean); unported types raise NotImplementedError (no
   fallback). transform/face_plane signatures fixed to the C++ surface;
   is_handle uses the real ShapeHandle type. Tessellation routes adacpp
   handles through the active backend's tessellate verb (adacpp's native
   ShapeTesselator port), pythonocc handles keep the rich ShapeTesselator
   path; vertex normals computed for the lean backend mesh.

End-to-end under ADAPY_CAD_BACKEND=adacpp: build + bbox + native tessellate +
GLB + boolean-cut all work for primitives, fully independent of pythonocc.
OccBackend unchanged: tests/core 655 pass (same 4 pre-existing failures),
ruff clean. Toward full ada.geom parity (ExtrudedAreaSolid + surfaces next).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Krande

src/ada/cad/__init__.py

@@ -85,14 +85,44 @@ def __init__(self) -> None:
         self._cad = cad
 
     def build(self, geometry: "Geometry") -> ShapeHandle:
-        # The full ada.geom.Geometry construction funnel is not ported to
-        # adacpp.cad yet — it currently exposes only primitive constructors
-        # (make_box/cylinder/sphere). Lands in a later phase of the CAD
-        # backend abstraction; until then callers fall back to OccBackend.
-        raise NotImplementedError(
-            "AdacppBackend.build() is not implemented yet — adacpp.cad only "
-            "supports primitive constructors so far."
-        )
+        # Native adacpp construction — NO pythonocc fallback. adacpp and the
+        # pythonocc backend must work independently (adacpp also targets wasm,
+        # where pythonocc does not exist). The ada.geom construction funnel is
+        # being ported to adacpp C++ incrementally; types not yet ported raise
+        # NotImplementedError rather than borrowing pythonocc. End goal: full
+        # parity with OccBackend. See dap plan/v3 Phase 7.
+        import ada.geom.solids as so
+
+        g = geometry.geometry
+
+        def _axis(d, default):
+            return list(d) if d is not None else list(default)
+
+        if isinstance(g, so.Box):
+            p = g.position
+            shape = self._cad.build_box(
+                list(p.location), _axis(p.axis, (0, 0, 1)), _axis(p.ref_direction, (1, 0, 0)),
+                g.x_length, g.y_length, g.z_length,
+            )
+        elif isinstance(g, so.Cylinder):
+            p = g.position
+            shape = self._cad.build_cylinder(list(p.location), _axis(p.axis, (0, 0, 1)), g.radius, g.height)
+        elif isinstance(g, so.Sphere):
+            shape = self._cad.build_sphere(list(g.center), g.radius)
+        elif isinstance(g, so.Cone):
+            p = g.position
+            shape = self._cad.build_cone(list(p.location), _axis(p.axis, (0, 0, 1)), g.bottom_radius, g.height)
+        else:
+            raise NotImplementedError(
+                f"AdacppBackend.build: ada.geom type {type(g).__name__!r} is not yet ported to "
+                "adacpp (no pythonocc fallback by design). Use ADAPY_CAD_BACKEND=occ for it, or "
+                "extend adacpp.cad."
+            )
+
+        # Apply booleans natively (operands built recursively in adacpp).
+        for op in geometry.bool_operations:
+            shape = self.boolean(op.operator, shape, self.build(op.second_operand))
+        return shape
 
     def make_box(self, dx: float, dy: float, dz: float) -> ShapeHandle:
         return self._cad.make_box(dx, dy, dz)
@@ -124,25 +154,25 @@ def write_glb_bytes(self, shape: ShapeHandle, linear_deflection: float = 0.1) ->
     def is_handle(self, obj: Any) -> bool:
         # Recognise an adacpp-native shape so callers can keep handle-type
         # introspection out of their own code (e.g. the tessellator's
-        # raw-import fast path). The wasm/native builds expose the concrete
-        # type as `adacpp.cad.Shape`; if a build omits it we conservatively
-        # report False (an unrecognised value is treated as "not a handle").
-        handle_t = getattr(self._cad, "Shape", None)
+        # raw-import fast path). adacpp.cad exposes the concrete type as
+        # `ShapeHandle`; if a build omits it we conservatively report False.
+        handle_t = getattr(self._cad, "ShapeHandle", None)
         return handle_t is not None and isinstance(obj, handle_t)
 
     def boolean(self, op: "BoolOpEnum", a: ShapeHandle, b: ShapeHandle) -> ShapeHandle:
-        # Lands with the Phase 7 adacpp.cad CSG surface; OccBackend covers
-        # native today.
         fn = getattr(self._cad, "boolean", None)
         if fn is None:
             raise NotImplementedError("adacpp.cad.boolean is not available in this build")
-        return fn(str(op.value), a, b)
+        return fn(op.value, a, b)
 
     def transform(self, shape: ShapeHandle, matrix: "np.ndarray", copy: bool = True) -> ShapeHandle:
         fn = getattr(self._cad, "transform", None)
         if fn is None:
             raise NotImplementedError("adacpp.cad.transform is not available in this build")
-        return fn(shape, matrix, copy)
+        # adacpp.cad.transform takes the top 3 rows of the 4x4 as 12 row-major
+        # doubles (implicit bottom row [0,0,0,1]).
+        m = [float(matrix[i][j]) for i in range(3) for j in range(4)]
+        return fn(shape, m, copy)
 
     def distance(self, a: ShapeHandle, b: ShapeHandle) -> float:
         fn = getattr(self._cad, "distance", None)
@@ -178,7 +208,16 @@ def face_plane(self, face: ShapeHandle) -> "tuple[Point, Direction] | None":
         fn = getattr(self._cad, "face_plane", None)
         if fn is None:
             raise NotImplementedError("adacpp.cad.face_plane is not available in this build")
-        return fn(face)
+        res = fn(face)
+        if res is None:
+            return None
+        # adacpp returns ((ox,oy,oz),(nx,ny,nz)); wrap into ada.geom types to
+        # match OccBackend.face_plane.
+        from ada.geom.direction import Direction
+        from ada.geom.points import Point
+
+        origin, normal = res
+        return Point(*origin), Direction(*normal)
 
     def from_topods_pointer(self, ptr: int) -> ShapeHandle:
         """Wrap an OCCT TopoDS_Shape addressed by a raw pointer.

src/ada/cadit/step/write/writer.py

@@ -11,6 +11,7 @@
     BRepBuilderAPI_MakeEdge2d,
     BRepBuilderAPI_MakeVertex,
 )
+from OCC.Core.BRepCheck import BRepCheck_Analyzer
 from OCC.Core.Geom import Geom_Curve
 from OCC.Core.Geom2d import Geom2d_BSplineCurve
 from OCC.Core.gp import gp_Pnt, gp_Pnt2d
@@ -22,7 +23,6 @@
 from OCC.Core.XSControl import XSControl_WorkSession
 
 from ada.base.units import Units
-from ada.cad import active_backend
 from ada.config import logger
 from ada.occ.xcaf_utils import set_color, set_name
 from ada.visit.colors import Color
@@ -85,14 +85,17 @@ def add_shape(self, shape: Any, name: str, rgb_color=None, parent=None):
                 logger.warning(f"Skipping NULL shape '{name}' (IsNull == True)")
                 return
 
-            # Validate topology via the CAD backend. If invalid, skip with a warning.
+            # Validate topology with BRepCheck. The STEP/XCAF writer is the
+            # OCC/pythonocc DocBackend implementation — it operates on raw
+            # TopoDS shapes, so it checks with OCC directly, not the active
+            # CAD backend. If invalid, skip with a warning.
             try:
-                if not active_backend().is_valid(shape):
-                    logger.warning(f"Skipping invalid shape '{name}' (is_valid == False)")
+                if not BRepCheck_Analyzer(shape, True).IsValid():
+                    logger.warning(f"Skipping invalid shape '{name}' (BRepCheck_Analyzer.IsValid == False)")
                     return
             except Exception as ex:
-                # If the validity check fails unexpectedly, log and continue without validation
-                logger.debug(f"is_valid check failed for shape '{name}': {ex}")
+                # If BRepCheck fails unexpectedly, log and continue without validation
+                logger.debug(f"BRepCheck_Analyzer failed for shape '{name}': {ex}")
 
             self.comp_builder.Add(self.comp, shape)
         except Exception as ex:

src/ada/occ/geom/boolean.py

@@ -1,17 +1,18 @@
+from OCC.Core.BRepAlgoAPI import BRepAlgoAPI_Common, BRepAlgoAPI_Cut, BRepAlgoAPI_Fuse
 from OCC.Core.BRepBuilderAPI import BRepBuilderAPI_MakeFace
 from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeHalfSpace
 from OCC.Core.gp import gp_Dir, gp_Pln, gp_Pnt
 from OCC.Core.TopoDS import TopoDS_Shape
 
-from ada.cad import active_backend
 from ada.geom.booleans import BooleanOperation, BoolOpEnum
 from ada.geom.surfaces import HalfSpaceSolid, Plane
 
 
 def apply_geom_booleans(geom: TopoDS_Shape, booleans: list[BooleanOperation]) -> TopoDS_Shape:
+    # OCC-internal: part of the pythonocc construction funnel (geom_to_occ_geom),
+    # so it applies booleans with OCC directly rather than the active backend.
     from ada.occ.geom import geom_to_occ_geom
 
-    backend = active_backend()
     for boolean in booleans:
         if isinstance(boolean.second_operand.geometry, HalfSpaceSolid):
             solid_geom = boolean.second_operand.geometry
@@ -39,9 +40,17 @@ def apply_geom_booleans(geom: TopoDS_Shape, booleans: list[BooleanOperation]) ->
             half_space = half_space_maker.Solid()
 
             # Apply the boolean cut operation (half-space is typically used for cutting)
-            geom = backend.boolean(BoolOpEnum.DIFFERENCE, geom, half_space)
+            geom = BRepAlgoAPI_Cut(geom, half_space).Shape()
 
             continue
-        geom = backend.boolean(boolean.operator, geom, geom_to_occ_geom(boolean.second_operand))
+        operand = geom_to_occ_geom(boolean.second_operand)
+        if boolean.operator == BoolOpEnum.DIFFERENCE:
+            geom = BRepAlgoAPI_Cut(geom, operand).Shape()
+        elif boolean.operator == BoolOpEnum.UNION:
+            geom = BRepAlgoAPI_Fuse(geom, operand).Shape()
+        elif boolean.operator == BoolOpEnum.INTERSECTION:
+            geom = BRepAlgoAPI_Common(geom, operand).Shape()
+        else:
+            raise NotImplementedError(f"Boolean operation {boolean.operator} not implemented")
 
     return geom

src/ada/occ/serializers.py

@@ -1,7 +1,9 @@
+from OCC.Core.BRepTools import breptools
 from OCC.Core.TopoDS import TopoDS_Shape
 
-from ada.cad import active_backend
-
 
 def serialize_shape(shape: TopoDS_Shape) -> str:
-    return active_backend().serialize(shape)
+    # OCC-internal: operates on raw pythonocc TopoDS shapes (STEP→IFC path),
+    # so it serializes with OCC directly rather than the active CAD backend.
+    breptools.Clean(shape)
+    return breptools.WriteToString(shape)

src/ada/occ/tessellating.py

@@ -49,6 +49,21 @@ class LineMesh:
     normals: np.ndarray = None
 
 
+def _vertex_normals(positions: np.ndarray, faces: np.ndarray) -> np.ndarray:
+    """Per-vertex normals (flat float32, len == len(positions)) from triangle
+    faces by area-weighted accumulation + normalization. Used for backend
+    tessellators that return positions + indices but no normals."""
+    verts = positions.reshape(-1, 3)
+    tris = faces.reshape(-1, 3).astype(np.int64)
+    normals = np.zeros_like(verts)
+    fn = np.cross(verts[tris[:, 1]] - verts[tris[:, 0]], verts[tris[:, 2]] - verts[tris[:, 0]])
+    for k in range(3):
+        np.add.at(normals, tris[:, k], fn)
+    lengths = np.linalg.norm(normals, axis=1, keepdims=True)
+    lengths[lengths == 0] = 1.0
+    return (normals / lengths).reshape(-1).astype("float32")
+
+
 def tessellate_edges(shape: TopoDS_Edge, deflection=0.01) -> LineMesh:
     points = discretize_edge(shape, deflection=deflection)
 
@@ -146,7 +161,7 @@ def tessellate_occ_geom(
             tess_shape = tessellate_edges(occ_geom)
             indices = tess_shape.indices
         else:
-            tess_shape = tessellate_shape(occ_geom, self.quality, self.render_edges, self.parallel)
+            tess_shape = self._triangulate(occ_geom)
             indices = tess_shape.faces
 
         mat_id = self.material_store.get(geom_color, None)
@@ -165,6 +180,26 @@ def tessellate_occ_geom(
             geom_ref,
         )
 
+    def _triangulate(self, occ_geom) -> TriangleMesh:
+        """Triangle-mesh a body. pythonocc TopoDS handles use the rich
+        ShapeTesselator (normals + edges). Any other handle (e.g. an adacpp
+        ShapeHandle) is tessellated through the active backend's tessellate
+        verb and adapted to a TriangleMesh — keeping the tessellation path
+        backend-independent. Normals are computed from the triangles since the
+        lean backend Mesh carries only positions + indices."""
+        from OCC.Core.TopoDS import TopoDS_Shape
+
+        if isinstance(occ_geom, TopoDS_Shape):
+            return tessellate_shape(occ_geom, self.quality, self.render_edges, self.parallel)
+
+        from ada.cad import active_backend
+
+        mesh = active_backend().tessellate(occ_geom)
+        positions = np.ascontiguousarray(mesh.positions, dtype="float32")
+        faces = np.ascontiguousarray(mesh.indices, dtype="uint32")
+        normals = _vertex_normals(positions, faces)
+        return TriangleMesh(positions, faces, None, normals)
+
     def tessellate_geom(
         self,
         geom: Geometry,