Merge hyperreal into main

# Conflicts:
#	PORTING_PLAN.md
#	src/io/stl.rs
#	src/main.rs
#	src/mesh/mod.rs
#	src/polygon.rs
#	src/sketch/extrudes.rs
#	src/tests.rs

Author: timschmidt

PORTING_PLAN.md

@@ -23,6 +23,32 @@ Those properties map directly to several current `csgrs` pain points: finite
 coordinate enforcement, deterministic map/set keys, explicit NaN/infinity
 policy, and centralized approximate comparisons.
 
+## Branch and commit discipline during the port
+
+Porting work should happen on a branch named `hyperreal` in each repository
+touched by the migration. This applies especially to:
+
+- `csgrs`
+- `spade`
+- `boolmesh`
+- `curvo`
+- `voxelis`
+
+The default branches should be treated as integration targets, not active
+porting branches. Before changing a repository for the port, switch that
+repository to its `hyperreal` branch or create it from the appropriate upstream
+base if it does not exist yet.
+
+During the porting period, each successful change should be verified, committed,
+and pushed automatically to that repository's `hyperreal` branch before moving
+on to the next independent change. Cross-repo work should be split into
+repository-local commits so `csgrs`, `spade`, `boolmesh`, `curvo`, and `voxelis`
+each retain a reviewable history of the port.
+
+After every successful commit and push, take another implementation turn against
+the next incomplete item in this plan. Continue that cycle until the plan is
+finished, tests expose a blocker, or a design decision requires human review.
+
 ## Target ownership model
 
 The stack should have clear vertical responsibilities:
@@ -40,12 +66,24 @@ csgrs         = CSG objects, modeling operations, topology, metadata, IO, and us
 
 - exact rationals
 - symbolic and computable reals
+- shared reduced expression machinery with symbolic leaves
+- standard-real solver variables and formal infinitesimal perturbation leaves
 - lazy approximation
 - sign, zero, magnitude, and structural facts
 - refinement and conservative comparison support
 
 It should not own CSG, polygon, mesh, or CAD-specific geometry types.
 
+The machinery needed for the feature that gives `hyperreal` its name should be
+developed together with the machinery needed to map a SolveSpace-style solver
+onto `hyperreal`, but the semantics should remain distinct. Both need reduced
+expression graphs, symbolic leaves, dependency sets, structural facts,
+derivative hooks, and cached evaluation. Solver variables are unknown standard
+reals that are bound by an evaluation context during iterative solving.
+Infinitesimal perturbations are ordered formal terms used for exact
+lexicographic signs, tie-breaking, degeneracy handling, and simulation of
+simplicity; they are not ordinary variables to solve for numerically.
+
 ### `hyperlattice`
 
 `hyperlattice` should own the general linear algebra layer:
@@ -356,6 +394,36 @@ yet operate on the new numeric stack:
   runners, and any other non-`csgrs` geometry implementation used during the
   port
 
+External geometry kernels should be handled on their own `hyperreal` branches.
+In particular, `spade`, `boolmesh`, `curvo`, and `voxelis` should not receive
+long-running uncommitted local patches during the `csgrs` migration. A verified
+change in one of those libraries should be committed and pushed to that
+library's `hyperreal` branch before `csgrs` is updated to depend on it.
+
+When a needed function is missing from `hyperlattice`, `hyperlimit`,
+`hypersolve`, or a future `hyperphysics` crate, the normal path should be to
+borrow the algorithm from an appropriately licensed crate, port it to
+`hyperreal`-compatible scalar and fact machinery, and extend the correct stack
+crate here. Crates such as `nalgebra` are valid sources when their licenses,
+attribution requirements, and implementation boundaries are compatible with the
+target crate. The goal is not to keep permanent f64-only adapter islands; it is
+to move useful, well-understood algorithms into the `hyperreal` stack so they
+share consistency, structural facts, exact/perturbed predicate behavior, and
+performance work with the rest of the system.
+
+Use this path for crates that should ultimately be ported to `hyperreal` for
+consistency and performance:
+
+- linear algebra, transforms, decomposition, and dense/sparse numeric kernels
+  belong in `hyperlattice`
+- robust geometric predicates, carriers, classification helpers, and
+  degeneracy policies belong in `hyperlimit`
+- solver residual, Jacobian, rank, projection, and constraint scheduling
+  helpers belong in `hypersolve`
+- physical simulation, dynamics, collision-response policy, material behavior,
+  or other non-geometric physics primitives should live in a separate
+  `hyperphysics` crate if they do not fit the existing ownership boundaries
+
 Keep these adapters private at first. The first milestone is internal
 correctness, not public API churn.
 
@@ -569,6 +637,41 @@ At this point, the semantic boundary should already be correct:
 The hyperreal port should therefore focus on backend behavior, performance, and
 additional certificates rather than rewriting `csgrs` modeling logic again.
 
+This phase should align with the `hypersolve` / SolveSpace-style symbolic
+variable work in `hyperreal`. The shared substrate should support:
+
+- expression nodes with symbolic leaves
+- dependency and independence facts
+- structural sign, zero, magnitude, and domain facts before full evaluation
+- reduced-expression caching across repeated queries
+- derivative hooks for solver residuals and, where useful, perturbation
+  propagation
+- bounded simplification so solver equations and infinitesimal series do not
+  grow without control
+
+The first infinitesimal target should be CAD-useful ordered perturbations, not a
+general nonstandard-analysis universe. A practical model is a finite
+lexicographic perturbation tower:
+
+```text
+standard Real + a1*eps + a2*eps^2 + ...
+```
+
+or an equivalent ordered perturbation-term representation. `hyperlimit` should
+be able to use these terms to decide predicate signs in degenerate cases without
+inventing ad hoc epsilon constants. `hypersolve` should use the same expression
+and fact infrastructure for standard-real variables, residuals, Jacobians, and
+rank diagnostics. The two paths should share representation, reduction,
+caching, and derivative infrastructure while keeping their policy layers
+separate:
+
+- solver symbols are bound by an evaluation context and participate in numeric
+  iteration
+- infinitesimal symbols are ordered formal perturbations and participate in
+  lexicographic comparison
+- `csgrs` consumes the resulting classifications and certificates, but still
+  owns CSG topology, metadata, and modeling policy
+
 ### Phase 10: Public API cleanup
 
 After internals are stable:
@@ -1818,6 +1921,13 @@ Show-off examples:
 
 ## Design rules during the port
 
+- Work on the `hyperreal` branch of each affected repository, especially
+  `csgrs`, `spade`, `boolmesh`, `curvo`, and `voxelis`.
+- Commit and push each verified successful change to that repository's
+  `hyperreal` branch before starting the next independent change.
+- After each successful commit and push, take another implementation turn on the
+  next unfinished porting-plan item, continuing until the plan is complete or a
+  blocker requires review.
 - Lower crates provide facts; `csgrs` makes modeling decisions.
 - Predicate uncertainty should be represented explicitly until `csgrs` decides
   how to handle it.

src/csg.rs

@@ -48,7 +48,7 @@ pub trait CSG: Sized + Clone {
     /// ```
     /// use csgrs::mesh::Mesh;
     /// use csgrs::csg::CSG;
-    /// let mesh = Mesh::<()>::cube(1.0, None).translate(2.0, 1.0, -2.0);
+    /// let mesh = Mesh::<()>::cube(1.0, ()).translate(2.0, 1.0, -2.0);
     /// let floated = mesh.float();
     /// assert_eq!(floated.bounding_box().mins.z, 0.0);
     /// ```

src/errors.rs

@@ -3,36 +3,78 @@
 use crate::float_types::Real;
 use nalgebra::Point3;
 
+/// Coordinate validation failure for a single point.
+#[derive(Clone, Debug, thiserror::Error, PartialEq)]
+pub enum PointError {
+    #[error("point {0:?} has NaN fields")]
+    NaN(Point3<Real>),
+    #[error("point {0:?} has infinite fields")]
+    Infinite(Point3<Real>),
+}
+
 /// All the possible validation issues we might encounter,
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, thiserror::Error, PartialEq)]
+#[non_exhaustive]
 pub enum ValidationError {
     /// (RepeatedPoint) Two consecutive coords are identical
+    #[error("point {0:?} is repeated consecutively")]
     RepeatedPoint(Point3<Real>),
     /// (HoleOutsideShell) A hole is *not* contained by its outer shell
+    #[error("hole is not contained by its outer shell near {0:?}")]
     HoleOutsideShell(Point3<Real>),
     /// (NestedHoles) A hole is nested inside another hole
+    #[error("hole is nested inside another hole near {0:?}")]
     NestedHoles(Point3<Real>),
     /// (DisconnectedInterior) The interior is disconnected
+    #[error("interior is disconnected near {0:?}")]
     DisconnectedInterior(Point3<Real>),
     /// (SelfIntersection) A polygon self‐intersects
+    #[error("polygon self-intersects near {0:?}")]
     SelfIntersection(Point3<Real>),
     /// (RingSelfIntersection) A linear ring has a self‐intersection
+    #[error("linear ring self-intersects near {0:?}")]
     RingSelfIntersection(Point3<Real>),
     /// (NestedShells) Two outer shells are nested incorrectly
+    #[error("outer shells are nested incorrectly near {0:?}")]
     NestedShells(Point3<Real>),
     /// (TooFewPoints) A ring or line has fewer than the minimal #points
+    #[error("ring or line has too few points near {0:?}")]
     TooFewPoints(Point3<Real>),
     /// (InvalidCoordinate) The coordinate has a NaN or infinite
+    #[error("invalid coordinate {0:?}")]
     InvalidCoordinate(Point3<Real>),
+    /// A more precise invalid-coordinate report.
+    #[error(transparent)]
+    PointError(#[from] PointError),
     /// (RingNotClosed) The ring's first/last points differ
+    #[error("ring is not closed near {0:?}")]
     RingNotClosed(Point3<Real>),
     /// (MismatchedVertices) operation requires polygons with same number of vertices
+    #[error("operation requires polygons with the same number of vertices")]
     MismatchedVertices,
+    /// Operation requires polygons with the same number of vertices.
+    #[error("operation requires polygons with the same number of vertices, {left} != {right}")]
+    MismatchedVertexCount { left: usize, right: usize },
     /// (IndexOutOfRange) operation requires polygons with same number of vertices
+    #[error("index out of range")]
     IndexOutOfRange,
+    /// A required index is outside a collection.
+    #[error("index {index} is out of range for length {len}")]
+    IndexOutOfRangeWithLen { index: usize, len: usize },
     /// (InvalidArguments) operation requires polygons with same number of vertices
+    #[error("invalid arguments")]
     InvalidArguments,
+    /// A named integer field is below the supported minimum.
+    #[error("{name} must not be less than {min}")]
+    FieldLessThan { name: &'static str, min: i32 },
+    /// A named real field is below the supported minimum.
+    #[error("{name} must not be less than {min}")]
+    FieldLessThanFloat { name: &'static str, min: Real },
+    /// An inconsistency while building a triangle mesh.
+    #[error("triangle mesh builder error: {0}")]
+    TriMeshError(String),
     /// In general, anything else
+    #[error("{0}")]
     Other(String, Option<Point3<Real>>),
 }
 

src/io/stl.rs

@@ -12,10 +12,9 @@ use stl_io;
 /// # use csgrs::mesh::Mesh;
 /// # use std::error::Error;
 /// # fn main() -> Result<(), Box<dyn Error>> {
-/// let mesh  = Mesh::<()>::cube(1.0, None);
+/// let mesh  = Mesh::<()>::cube(1.0, ());
 /// let bytes = mesh.to_stl_ascii("my_solid");
-/// std::fs::create_dir_all("stl")?;
-/// std::fs::write("stl/my_solid.stl", bytes)?;
+/// assert!(bytes.starts_with("solid my_solid"));
 /// # Ok(())
 /// # }
 /// ```
@@ -49,10 +48,9 @@ pub fn to_stl_ascii<T: Triangulated3D>(shape: &T, name: &str) -> String {
 /// # use csgrs::mesh::Mesh;
 /// # use std::error::Error;
 /// # fn main() -> Result<(), Box<dyn Error>> {
-/// let object = Mesh::<()>::cube(1.0, None);
+/// let object = Mesh::<()>::cube(1.0, ());
 /// let bytes  = object.to_stl_binary("my_solid")?;
-/// std::fs::create_dir_all("stl")?;
-/// std::fs::write("stl/my_solid.stl", bytes)?;
+/// assert!(!bytes.is_empty());
 /// # Ok(())
 /// # }
 /// ```

src/mesh/flatten_slice.rs

@@ -90,7 +90,7 @@ impl<M: Clone + Debug + Send + Sync> Mesh<M> {
     /// use csgrs::mesh::plane::Plane;
     /// use csgrs::sketch::Sketch;
     /// use nalgebra::Vector3;
-    /// let cylinder = Mesh::<()>::cylinder(1.0, 2.0, 32, None);
+    /// let cylinder = Mesh::<()>::cylinder(1.0, 2.0, 32, ());
     /// let plane_z0 = Plane::from_normal(Vector3::z(), 0.0);
     /// let cross_section = cylinder.slice(plane_z0);
     /// // `cross_section` will contain:

src/mesh/mod.rs

@@ -1,5 +1,6 @@
 //! `Mesh` struct and implementations of the `CSGOps` trait for `Mesh`
 
+use crate::errors::ValidationError;
 use crate::float_types::{
     parry3d::{bounding_volume::Aabb, query::RayCast, shape::Shape},
     rapier3d::prelude::{
@@ -357,13 +358,13 @@ impl<M: Clone + Send + Sync + Debug> Mesh<M> {
     /// ```
     /// use csgrs::mesh::Mesh;
     /// use core::num::NonZeroU32;
-    /// let mut cube: Mesh<()> = Mesh::cube(2.0, None);
+    /// let mut cube: Mesh<()> = Mesh::cube(2.0, ());
     /// // subdivide_triangles(1) => each polygon (quad) is triangulated => 2 triangles => each tri subdivides => 4
     /// // So each face with 4 vertices => 2 triangles => each becomes 4 => total 8 per face => 6 faces => 48
     /// cube.subdivide_triangles_mut(1.try_into().expect("not zero"));
     /// assert_eq!(cube.polygons.len(), 48);
     ///
-    /// let mut cube: Mesh<()> = Mesh::cube(2.0, None);
+    /// let mut cube: Mesh<()> = Mesh::cube(2.0, ());
     /// cube.subdivide_triangles_mut(2.try_into().expect("not zero"));
     /// assert_eq!(cube.polygons.len(), 192);
     /// ```
@@ -597,29 +598,34 @@ impl<M: Clone + Send + Sync + Debug> Mesh<M> {
     ///
     /// ## Errors
     /// If any 3d polygon has fewer than 3 vertices, or Parry returns a `TriMeshBuilderError`
-    pub fn to_rapier_shape(&self) -> SharedShape {
+    pub fn to_rapier_shape(&self) -> Result<SharedShape, ValidationError> {
         let (vertices, indices) = self.get_vertices_and_indices();
-        let trimesh = TriMesh::new(vertices, indices).unwrap();
-        SharedShape::new(trimesh)
+        let trimesh = TriMesh::new(vertices, indices)
+            .map_err(|err| ValidationError::TriMeshError(format!("{err:?}")))?;
+        Ok(SharedShape::new(trimesh))
     }
 
     /// Convert the polygons in this Mesh to a Parry `TriMesh`.\
     /// Useful for collision detection.
     ///
     /// ## Errors
     /// If any 3d polygon has fewer than 3 vertices, or Parry returns a `TriMeshBuilderError`
-    pub fn to_trimesh(&self) -> Option<TriMesh> {
+    pub fn to_trimesh(&self) -> Result<TriMesh, ValidationError> {
         let (vertices, indices) = self.get_vertices_and_indices();
-        TriMesh::new(vertices, indices).ok()
+        TriMesh::new(vertices, indices)
+            .map_err(|err| ValidationError::TriMeshError(format!("{err:?}")))
     }
 
-    fn cached_trimesh(&self) -> Option<&TriMesh> {
+    fn cached_trimesh(&self) -> Result<&TriMesh, ValidationError> {
         self.query_trimesh
             .get_or_init(|| {
                 let (vertices, indices) = self.get_vertices_and_indices();
                 TriMesh::new(vertices, indices).ok()
             })
             .as_ref()
+            .ok_or_else(|| {
+                ValidationError::TriMeshError("failed to build triangle mesh".into())
+            })
     }
 
     /// Uses Parry to check if a point is inside a `Mesh`'s as a `TriMesh`.\
@@ -633,7 +639,7 @@ impl<M: Clone + Send + Sync + Debug> Mesh<M> {
     /// # use csgrs::mesh::Mesh;
     /// # use nalgebra::Point3;
     /// # use nalgebra::Vector3;
-    /// let csg_cube = Mesh::<()>::cube(6.0, None);
+    /// let csg_cube = Mesh::<()>::cube(6.0, ());
     ///
     /// assert!(csg_cube.contains_vertex(&Point3::new(3.0, 3.0, 3.0)));
     /// assert!(csg_cube.contains_vertex(&Point3::new(1.0, 2.0, 5.9)));
@@ -652,15 +658,15 @@ impl<M: Clone + Send + Sync + Debug> Mesh<M> {
     pub fn mass_properties(
         &self,
         density: Real,
-    ) -> (Real, Point3<Real>, Unit<Quaternion<Real>>) {
-        let trimesh = self.cached_trimesh().unwrap();
+    ) -> Result<(Real, Point3<Real>, Unit<Quaternion<Real>>), ValidationError> {
+        let trimesh = self.cached_trimesh()?;
         let mp = trimesh.mass_properties(density);
 
-        (
+        Ok((
             mp.mass(),
             mp.local_com,                     // a Point3<Real>
             mp.principal_inertia_local_frame, // a Unit<Quaternion<Real>>
-        )
+        ))
     }
 
     /// Create a Rapier rigid body + collider from this Mesh, using
@@ -673,8 +679,8 @@ impl<M: Clone + Send + Sync + Debug> Mesh<M> {
         translation: Vector3<Real>,
         rotation: Vector3<Real>, // rotation axis scaled by angle (radians)
         density: Real,
-    ) -> RigidBodyHandle {
-        let shape = self.to_rapier_shape();
+    ) -> Result<RigidBodyHandle, ValidationError> {
+        let shape = self.to_rapier_shape()?;
 
         // Build a Rapier RigidBody
         let rb = RigidBodyBuilder::dynamic()
@@ -688,7 +694,7 @@ impl<M: Clone + Send + Sync + Debug> Mesh<M> {
         let coll = ColliderBuilder::new(shape).density(density).build();
         co_set.insert_with_parent(coll, rb_handle, rb_set);
 
-        rb_handle
+        Ok(rb_handle)
     }
 
     /// Convert a Mesh into a Bevy `Mesh`.

src/mesh/sdf.rs

@@ -22,7 +22,7 @@ impl<M: Clone + Debug + Send + Sync> Mesh<M> {
     /// let max_pt = Point3::new( 2.0,  2.0,  2.0);
     /// let iso_value = 0.0; // Typically zero for SDF-based surfaces
     ///
-    ///    let mesh_shape = Mesh::<()>::sdf(my_sdf, resolution, min_pt, max_pt, iso_value, None);
+    ///    let mesh_shape = Mesh::<()>::sdf(my_sdf, resolution, min_pt, max_pt, iso_value, ());
     ///
     ///    // Now `mesh_shape` is your polygon mesh as a Mesh you can union, subtract, or export:
     ///    let _ = std::fs::write("stl/sdf_sphere.stl", mesh_shape.to_stl_binary("sdf_sphere").unwrap());